avr/qmk/firmware - [no description]

diff options

author	noroadsleft <18669334+noroadsleft@users.noreply.github.com>	2019-06-04 20:29:05 -0700
committer	Drashna Jaelre <drashna@live.com>	2019-06-04 20:29:05 -0700
commit	a63e2abc9c1fc945997380db926ec2cdd0fd1034 (patch)
tree	cec9544d6f9a5f0dd5927f403920bdb1ce3ec20f /lib/lufa/Projects/LEDNotifier/CPUUsageApp/Properties/Resources.Designer.cs
parent	e0a0d80bd329b4a289e3c4f817c96857c25b0f16 (diff)
download	firmware-a63e2abc9c1fc945997380db926ec2cdd0fd1034.tar.gz firmware-a63e2abc9c1fc945997380db926ec2cdd0fd1034.tar.bz2 firmware-a63e2abc9c1fc945997380db926ec2cdd0fd1034.zip

[Keyboard] Fix Configurator support for Mulletpad (#6074)

- correct layout macro name - correct JSON object ordering

Diffstat (limited to 'lib/lufa/Projects/LEDNotifier/CPUUsageApp/Properties/Resources.Designer.cs')

0 files changed, 0 insertions, 0 deletions

\documentclass[11pt,twoside,final,openright,a4paper]{report} \usepackage{graphicx,html,setspace,times} \usepackage{parskip} \setstretch{1.15} % LIBRARY FUNCTIONS \newcommand{\hypercall}[1]{\vspace{2mm}{\sf #1}} \begin{document} % TITLE PAGE \pagestyle{empty} \begin{center} \vspace*{\fill} \includegraphics{figs/xenlogo.eps} \vfill \vfill \vfill \begin{tabular}{l} {\Huge \bf Interface manual} \\[4mm] {\huge Xen v3.0 for x86} \\[80mm] {\Large Xen is Copyright (c) 2002-2005, The Xen Team} \\[3mm] {\Large University of Cambridge, UK} \\[20mm] \end{tabular} \end{center} {\bf DISCLAIMER: This documentation is always under active development and as such there may be mistakes and omissions --- watch out for these and please report any you find to the developer's mailing list. The latest version is always available on-line. Contributions of material, suggestions and corrections are welcome. } \vfill \cleardoublepage % TABLE OF CONTENTS \pagestyle{plain} \pagenumbering{roman} { \parskip 0pt plus 1pt \tableofcontents } \cleardoublepage % PREPARE FOR MAIN TEXT \pagenumbering{arabic} \raggedbottom \widowpenalty=10000 \clubpenalty=10000 \parindent=0pt \parskip=5pt \renewcommand{\topfraction}{.8} \renewcommand{\bottomfraction}{.8} \renewcommand{\textfraction}{.2} \renewcommand{\floatpagefraction}{.8} \setstretch{1.1} \chapter{Introduction} Xen allows the hardware resources of a machine to be virtualized and dynamically partitioned, allowing multiple different {\em guest} operating system images to be run simultaneously. Virtualizing the machine in this manner provides considerable flexibility, for example allowing different users to choose their preferred operating system (e.g., Linux, NetBSD, or a custom operating system). Furthermore, Xen provides secure partitioning between virtual machines (known as {\em domains} in Xen terminology), and enables better resource accounting and QoS isolation than can be achieved with a conventional operating system. Xen essentially takes a `whole machine' virtualization approach as pioneered by IBM VM/370. However, unlike VM/370 or more recent efforts such as VMware and Virtual PC, Xen does not attempt to completely virtualize the underlying hardware. Instead parts of the hosted guest operating systems are modified to work with the VMM; the operating system is effectively ported to a new target architecture, typically requiring changes in just the machine-dependent code. The user-level API is unchanged, and so existing binaries and operating system distributions work without modification. In addition to exporting virtualized instances of CPU, memory, network and block devices, Xen exposes a control interface to manage how these resources are shared between the running domains. Access to the control interface is restricted: it may only be used by one specially-privileged VM, known as {\em domain 0}. This domain is a required part of any Xen-based server and runs the application software that manages the control-plane aspects of the platform. Running the control software in {\it domain 0}, distinct from the hypervisor itself, allows the Xen framework to separate the notions of mechanism and policy within the system. \chapter{Virtual Architecture} In a Xen/x86 system, only the hypervisor runs with full processor privileges ({\it ring 0} in the x86 four-ring model). It has full access to the physical memory available in the system and is responsible for allocating portions of it to running domains. On a 32-bit x86 system, guest operating systems may use {\it rings 1}, {\it 2} and {\it 3} as they see fit. Segmentation is used to prevent the guest OS from accessing the portion of the address space that is reserved for Xen. We expect most guest operating systems will use ring 1 for their own operation and place applications in ring 3. On 64-bit systems it is not possible to protect the hypervisor from untrusted guest code running in rings 1 and 2. Guests are therefore restricted to run in ring 3 only. The guest kernel is protected from its applications by context switching between the kernel and currently running application. In this chapter we consider the basic virtual architecture provided by Xen: CPU state, exception and interrupt handling, and time. Other aspects such as memory and device access are discussed in later chapters. \section{CPU state} All privileged state must be handled by Xen. The guest OS has no direct access to CR3 and is not permitted to update privileged bits in EFLAGS. Guest OSes use \emph{hypercalls} to invoke operations in Xen; these are analogous to system calls but occur from ring 1 to ring 0. A list of all hypercalls is given in Appendix~\ref{a:hypercalls}. \section{Exceptions} A virtual IDT is provided --- a domain can submit a table of trap handlers to Xen via the {\bf set\_trap\_table} hypercall. The exception stack frame presented to a virtual trap handler is identical to its native equivalent. \section{Interrupts and events} Interrupts are virtualized by mapping them to \emph{event channels}, which are delivered asynchronously to the target domain using a callback supplied via the {\bf set\_callbacks} hypercall. A guest OS can map these events onto its standard interrupt dispatch mechanisms. Xen is responsible for determining the target domain that will handle each physical interrupt source. For more details on the binding of event sources to event channels, see Chapter~\ref{c:devices}. \section{Time} Guest operating systems need to be aware of the passage of both real (or wallclock) time and their own `virtual time' (the time for which they have been executing). Furthermore, Xen has a notion of time which is used for scheduling. The following notions of time are provided: \begin{description} \item[Cycle counter time.] This provides a fine-grained time reference. The cycle counter time is used to accurately extrapolate the other time references. On SMP machines it is currently assumed that the cycle counter time is synchronized between CPUs. The current x86-based implementation achieves this within inter-CPU communication latencies. \item[System time.] This is a 64-bit counter which holds the number of nanoseconds that have elapsed since system boot. \item[Wall clock time.] This is the time of day in a Unix-style {\bf struct timeval} (seconds and microseconds since 1 January 1970, adjusted by leap seconds). An NTP client hosted by {\it domain 0} can keep this value accurate. \item[Domain virtual time.] This progresses at the same pace as system time, but only while a domain is executing --- it stops while a domain is de-scheduled. Therefore the share of the CPU that a domain receives is indicated by the rate at which its virtual time increases. \end{description} Xen exports timestamps for system time and wall-clock time to guest operating systems through a shared page of memory. Xen also provides the cycle counter time at the instant the timestamps were calculated, and the CPU frequency in Hertz. This allows the guest to extrapolate system and wall-clock times accurately based on the current cycle counter time. Since all time stamps need to be updated and read \emph{atomically} a version number is also stored in the shared info page, which is incremented before and after updating the timestamps. Thus a guest can be sure that it read a consistent state by checking the two version numbers are equal and even. Xen includes a periodic ticker which sends a timer event to the currently executing domain every 10ms. The Xen scheduler also sends a timer event whenever a domain is scheduled; this allows the guest OS to adjust for the time that has passed while it has been inactive. In addition, Xen allows each domain to request that they receive a timer event sent at a specified system time by using the {\bf set\_timer\_op} hypercall. Guest OSes may use this timer to implement timeout values when they block. \section{Xen CPU Scheduling} Xen offers a uniform API for CPU schedulers. It is possible to choose from a number of schedulers at boot and it should be easy to add more. The SEDF and Credit schedulers are part of the normal Xen distribution. SEDF will be going away and its use should be avoided once the credit scheduler has stabilized and become the default. The Credit scheduler provides proportional fair shares of the host's CPUs to the running domains. It does this while transparently load balancing runnable VCPUs across the whole system. \paragraph*{Note: SMP host support} Xen has always supported SMP host systems. When using the credit scheduler, a domain's VCPUs will be dynamically moved across physical CPUs to maximise domain and system throughput. VCPUs can also be manually restricted to be mapped only on a subset of the host's physical CPUs, using the pinning mechanism. %% More information on the characteristics and use of these schedulers %% is available in {\bf Sched-HOWTO.txt}. \section{Privileged operations} Xen exports an extended interface to privileged domains (viz.\ {\it Domain 0}). This allows such domains to build and boot other domains on the server, and provides control interfaces for managing scheduling, memory, networking, and block devices. \chapter{Memory} \label{c:memory} Xen is responsible for managing the allocation of physical memory to domains, and for ensuring safe use of the paging and segmentation hardware. \section{Memory Allocation} As well as allocating a portion of physical memory for its own private use, Xen also reserves s small fixed portion of every virtual address space. This is located in the top 64MB on 32-bit systems, the top 168MB on PAE systems, and a larger portion in the middle of the address space on 64-bit systems. Unreserved physical memory is available for allocation to domains at a page granularity. Xen tracks the ownership and use of each page, which allows it to enforce secure partitioning between domains. Each domain has a maximum and current physical memory allocation. A guest OS may run a `balloon driver' to dynamically adjust its current memory allocation up to its limit. \section{Pseudo-Physical Memory} Since physical memory is allocated and freed on a page granularity, there is no guarantee that a domain will receive a contiguous stretch of physical memory. However most operating systems do not have good support for operating in a fragmented physical address space. To aid porting such operating systems to run on top of Xen, we make a distinction between \emph{machine memory} and \emph{pseudo-physical memory}. Put simply, machine memory refers to the entire amount of memory installed in the machine, including that reserved by Xen, in use by various domains, or currently unallocated. We consider machine memory to comprise a set of 4kB \emph{machine page frames} numbered consecutively starting from 0. Machine frame numbers mean the same within Xen or any domain. Pseudo-physical memory, on the other hand, is a per-domain abstraction. It allows a guest operating system to consider its memory allocation to consist of a contiguous range of physical page frames starting at physical frame 0, despite the fact that the underlying machine page frames may be sparsely allocated and in any order. To achieve this, Xen maintains a globally readable {\it machine-to-physical} table which records the mapping from machine page frames to pseudo-physical ones. In addition, each domain is supplied with a {\it physical-to-machine} table which performs the inverse mapping. Clearly the machine-to-physical table has size proportional to the amount of RAM installed in the machine, while each physical-to-machine table has size proportional to the memory allocation of the given domain. Architecture dependent code in guest operating systems can then use the two tables to provide the abstraction of pseudo-physical memory. In general, only certain specialized parts of the operating system (such as page table management) needs to understand the difference between machine and pseudo-physical addresses. \section{Page Table Updates} In the default mode of operation, Xen enforces read-only access to page tables and requires guest operating systems to explicitly request any modifications. Xen validates all such requests and only applies updates that it deems safe. This is necessary to prevent domains from adding arbitrary mappings to their page tables. To aid validation, Xen associates a type and reference count with each memory page. A page has one of the following mutually-exclusive types at any point in time: page directory ({\sf PD}), page table ({\sf PT}), local descriptor table ({\sf LDT}), global descriptor table ({\sf GDT}), or writable ({\sf RW}). Note that a guest OS may always create readable mappings of its own memory regardless of its current type. %%% XXX: possibly explain more about ref count 'lifecyle' here? This mechanism is used to maintain the invariants required for safety; for example, a domain cannot have a writable mapping to any part of a page table as this would require the page concerned to simultaneously be of types {\sf PT} and {\sf RW}. \hypercall{mmu\_update(mmu\_update\_t *req, int count, int *success\_count, domid\_t domid)} This hypercall is used to make updates to either the domain's pagetables or to the machine to physical mapping table. It supports submitting a queue of updates, allowing batching for maximal performance. Explicitly queuing updates using this interface will cause any outstanding writable pagetable state to be flushed from the system. \section{Writable Page Tables} Xen also provides an alternative mode of operation in which guests have the illusion that their page tables are directly writable. Of course this is not really the case, since Xen must still validate modifications to ensure secure partitioning. To this end, Xen traps any write attempt to a memory page of type {\sf PT} (i.e., that is currently part of a page table). If such an access occurs, Xen temporarily allows write access to that page while at the same time \emph{disconnecting} it from the page table that is currently in use. This allows the guest to safely make updates to the page because the newly-updated entries cannot be used by the MMU until Xen revalidates and reconnects the page. Reconnection occurs automatically in a number of situations: for example, when the guest modifies a different page-table page, when the domain is preempted, or whenever the guest uses Xen's explicit page-table update interfaces. Writable pagetable functionality is enabled when the guest requests it, using a {\bf vm\_assist} hypercall. Writable pagetables do {\em not} provide full virtualisation of the MMU, so the memory management code of the guest still needs to be aware that it is running on Xen. Since the guest's page tables are used directly, it must translate pseudo-physical addresses to real machine addresses when building page table entries. The guest may not attempt to map its own pagetables writably, since this would violate the memory type invariants; page tables will automatically be made writable by the hypervisor, as necessary. \section{Shadow Page Tables} Finally, Xen also supports a form of \emph{shadow page tables} in which the guest OS uses a independent copy of page tables which are unknown to the hardware (i.e.\ which are never pointed to by {\tt cr3}). Instead Xen propagates changes made to the guest's tables to the real ones, and vice versa. This is useful for logging page writes (e.g.\ for live migration or checkpoint). A full version of the shadow page tables also allows guest OS porting with less effort. \section{Segment Descriptor Tables} At start of day a guest is supplied with a default GDT, which does not reside within its own memory allocation. If the guest wishes to use other than the default `flat' ring-1 and ring-3 segments that this GDT provides, it must register a custom GDT and/or LDT with Xen, allocated from its own memory. The following hypercall is used to specify a new GDT: \begin{quote} int {\bf set\_gdt}(unsigned long *{\em frame\_list}, int {\em entries}) \emph{frame\_list}: An array of up to 14 machine page frames within which the GDT resides. Any frame registered as a GDT frame may only be mapped read-only within the guest's address space (e.g., no writable mappings, no use as a page-table page, and so on). Only 14 pages may be specified because pages 15 and 16 are reserved for the hypervisor's GDT entries. \emph{entries}: The number of descriptor-entry slots in the GDT. \end{quote} The LDT is updated via the generic MMU update mechanism (i.e., via the {\bf mmu\_update} hypercall. \section{Start of Day} The start-of-day environment for guest operating systems is rather different to that provided by the underlying hardware. In particular, the processor is already executing in protected mode with paging enabled. {\it Domain 0} is created and booted by Xen itself. For all subsequent domains, the analogue of the boot-loader is the {\it domain builder}, user-space software running in {\it domain 0}. The domain builder is responsible for building the initial page tables for a domain and loading its kernel image at the appropriate virtual address. \section{VM assists} Xen provides a number of ``assists'' for guest memory management. These are available on an ``opt-in'' basis to provide commonly-used extra functionality to a guest. \hypercall{vm\_assist(unsigned int cmd, unsigned int type)} The {\bf cmd} parameter describes the action to be taken, whilst the {\bf type} parameter describes the kind of assist that is being referred to. Available commands are as follows: \begin{description} \item[VMASST\_CMD\_enable] Enable a particular assist type \item[VMASST\_CMD\_disable] Disable a particular assist type \end{description} And the available types are: \begin{description} \item[VMASST\_TYPE\_4gb\_segments] Provide emulated support for instructions that rely on 4GB segments (such as the techniques used by some TLS solutions). \item[VMASST\_TYPE\_4gb\_segments\_notify] Provide a callback to the guest if the above segment fixups are used: allows the guest to display a warning message during boot. \item[VMASST\_TYPE\_writable\_pagetables] Enable writable pagetable mode - described above. \end{description} \chapter{Xen Info Pages} The {\bf Shared info page} is used to share various CPU-related state between the guest OS and the hypervisor. This information includes VCPU status, time information and event channel (virtual interrupt) state. The {\bf Start info page} is used to pass build-time information to the guest when it boots and when it is resumed from a suspended state. This chapter documents the fields included in the {\bf shared\_info\_t} and {\bf start\_info\_t} structures for use by the guest OS. \section{Shared info page} The {\bf shared\_info\_t} is accessed at run time by both Xen and the guest OS. It is used to pass information relating to the virtual CPU and virtual machine state between the OS and the hypervisor. The structure is declared in {\bf xen/include/public/xen.h}: \scriptsize \begin{verbatim} typedef struct shared_info { vcpu_info_t vcpu_info[MAX_VIRT_CPUS]; /* * A domain can create "event channels" on which it can send and receive * asynchronous event notifications. There are three classes of event that * are delivered by this mechanism: * 1. Bi-directional inter- and intra-domain connections. Domains must * arrange out-of-band to set up a connection (usually by allocating * an unbound 'listener' port and advertising that via a storage service * such as xenstore). * 2. Physical interrupts. A domain with suitable hardware-access * privileges can bind an event-channel port to a physical interrupt * source. * 3. Virtual interrupts ('events'). A domain can bind an event-channel * port to a virtual interrupt source, such as the virtual-timer * device or the emergency console. * * Event channels are addressed by a "port index". Each channel is * associated with two bits of information: * 1. PENDING -- notifies the domain that there is a pending notification * to be processed. This bit is cleared by the guest. * 2. MASK -- if this bit is clear then a 0->1 transition of PENDING * will cause an asynchronous upcall to be scheduled. This bit is only * updated by the guest. It is read-only within Xen. If a channel * becomes pending while the channel is masked then the 'edge' is lost * (i.e., when the channel is unmasked, the guest must manually handle * pending notifications as no upcall will be scheduled by Xen). * * To expedite scanning of pending notifications, any 0->1 pending * transition on an unmasked channel causes a corresponding bit in a * per-vcpu selector word to be set. Each bit in the selector covers a * 'C long' in the PENDING bitfield array. */ unsigned long evtchn_pending[sizeof(unsigned long) * 8]; unsigned long evtchn_mask[sizeof(unsigned long) * 8]; /* * Wallclock time: updated only by control software. Guests should base * their gettimeofday() syscall on this wallclock-base value. */ uint32_t wc_version; /* Version counter: see vcpu_time_info_t. */ uint32_t wc_sec; /* Secs 00:00:00 UTC, Jan 1, 1970. */ uint32_t wc_nsec; /* Nsecs 00:00:00 UTC, Jan 1, 1970. */ arch_shared_info_t arch; } shared_info_t; \end{verbatim} \normalsize \begin{description} \item[vcpu\_info] An array of {\bf vcpu\_info\_t} structures, each of which holds either runtime information about a virtual CPU, or is ``empty'' if the corresponding VCPU does not exist. \item[evtchn\_pending] Guest-global array, with one bit per event channel. Bits are set if an event is currently pending on that channel. \item[evtchn\_mask] Guest-global array for masking notifications on event channels. \item[wc\_version] Version counter for current wallclock time. \item[wc\_sec] Whole seconds component of current wallclock time. \item[wc\_nsec] Nanoseconds component of current wallclock time. \item[arch] Host architecture-dependent portion of the shared info structure. \end{description} \subsection{vcpu\_info\_t} \scriptsize \begin{verbatim} typedef struct vcpu_info { /* * 'evtchn_upcall_pending' is written non-zero by Xen to indicate * a pending notification for a particular VCPU. It is then cleared * by the guest OS /before/ checking for pending work, thus avoiding * a set-and-check race. Note that the mask is only accessed by Xen * on the CPU that is currently hosting the VCPU. This means that the * pending and mask flags can be updated by the guest without special * synchronisation (i.e., no need for the x86 LOCK prefix). * This may seem suboptimal because if the pending flag is set by * a different CPU then an IPI may be scheduled even when the mask * is set. However, note: * 1. The task of 'interrupt holdoff' is covered by the per-event- * channel mask bits. A 'noisy' event that is continually being * triggered can be masked at source at this very precise * granularity. * 2. The main purpose of the per-VCPU mask is therefore to restrict * reentrant execution: whether for concurrency control, or to * prevent unbounded stack usage. Whatever the purpose, we expect * that the mask will be asserted only for short periods at a time, * and so the likelihood of a 'spurious' IPI is suitably small. * The mask is read before making an event upcall to the guest: a * non-zero mask therefore guarantees that the VCPU will not receive * an upcall activation. The mask is cleared when the VCPU requests * to block: this avoids wakeup-waiting races. */ uint8_t evtchn_upcall_pending; uint8_t evtchn_upcall_mask; unsigned long evtchn_pending_sel; arch_vcpu_info_t arch; vcpu_time_info_t time; } vcpu_info_t; /* 64 bytes (x86) */ \end{verbatim} \normalsize \begin{description} \item[evtchn\_upcall\_pending] This is set non-zero by Xen to indicate that there are pending events to be received. \item[evtchn\_upcall\_mask] This is set non-zero to disable all interrupts for this CPU for short periods of time. If individual event channels need to be masked, the {\bf evtchn\_mask} in the {\bf shared\_info\_t} is used instead. \item[evtchn\_pending\_sel] When an event is delivered to this VCPU, a bit is set in this selector to indicate which word of the {\bf evtchn\_pending} array in the {\bf shared\_info\_t} contains the event in question. \item[arch] Architecture-specific VCPU info. On x86 this contains the virtualized CR2 register (page fault linear address) for this VCPU. \item[time] Time values for this VCPU. \end{description} \subsection{vcpu\_time\_info} \scriptsize \begin{verbatim} typedef struct vcpu_time_info { /* * Updates to the following values are preceded and followed by an * increment of 'version'. The guest can therefore detect updates by * looking for changes to 'version'. If the least-significant bit of * the version number is set then an update is in progress and the guest * must wait to read a consistent set of values. * The correct way to interact with the version number is similar to * Linux's seqlock: see the implementations of read_seqbegin/read_seqretry. */ uint32_t version; uint32_t pad0; uint64_t tsc_timestamp; /* TSC at last update of time vals. */ uint64_t system_time; /* Time, in nanosecs, since boot. */ /* * Current system time: * system_time + ((tsc - tsc_timestamp) << tsc_shift) * tsc_to_system_mul * CPU frequency (Hz): * ((10^9 << 32) / tsc_to_system_mul) >> tsc_shift */ uint32_t tsc_to_system_mul; int8_t tsc_shift; int8_t pad1[3]; } vcpu_time_info_t; /* 32 bytes */ \end{verbatim} \normalsize \begin{description} \item[version] Used to ensure the guest gets consistent time updates. \item[tsc\_timestamp] Cycle counter timestamp of last time value; could be used to expolate in between updates, for instance. \item[system\_time] Time since boot (nanoseconds). \item[tsc\_to\_system\_mul] Cycle counter to nanoseconds multiplier (used in extrapolating current time). \item[tsc\_shift] Cycle counter to nanoseconds shift (used in extrapolating current time). \end{description} \subsection{arch\_shared\_info\_t} On x86, the {\bf arch\_shared\_info\_t} is defined as follows (from xen/public/arch-x86\_32.h): \scriptsize \begin{verbatim} typedef struct arch_shared_info { unsigned long max_pfn; /* max pfn that appears in table */ /* Frame containing list of mfns containing list of mfns containing p2m. */ unsigned long pfn_to_mfn_frame_list_list; } arch_shared_info_t; \end{verbatim} \normalsize \begin{description} \item[max\_pfn] The maximum PFN listed in the physical-to-machine mapping table (P2M table). \item[pfn\_to\_mfn\_frame\_list\_list] Machine address of the frame that contains the machine addresses of the P2M table frames. \end{description} \section{Start info page} The start info structure is declared as the following (in {\bf xen/include/public/xen.h}): \scriptsize \begin{verbatim} #define MAX_GUEST_CMDLINE 1024 typedef struct start_info { /* THE FOLLOWING ARE FILLED IN BOTH ON INITIAL BOOT AND ON RESUME. */ char magic[32]; /* "Xen-<version>.<subversion>". */ unsigned long nr_pages; /* Total pages allocated to this domain. */ unsigned long shared_info; /* MACHINE address of shared info struct. */ uint32_t flags; /* SIF_xxx flags. */ unsigned long store_mfn; /* MACHINE page number of shared page. */ uint32_t store_evtchn; /* Event channel for store communication. */ unsigned long console_mfn; /* MACHINE address of console page. */ uint32_t console_evtchn; /* Event channel for console messages. */ /* THE FOLLOWING ARE ONLY FILLED IN ON INITIAL BOOT (NOT RESUME). */ unsigned long pt_base; /* VIRTUAL address of page directory. */ unsigned long nr_pt_frames; /* Number of bootstrap p.t. frames. */ unsigned long mfn_list; /* VIRTUAL address of page-frame list. */ unsigned long mod_start; /* VIRTUAL address of pre-loaded module. */ unsigned long mod_len; /* Size (bytes) of pre-loaded module. */ int8_t cmd_line[MAX_GUEST_CMDLINE]; } start_info_t; \end{verbatim} \normalsize The fields are in two groups: the first group are always filled in when a domain is booted or resumed, the second set are only used at boot time. The always-available group is as follows: \begin{description} \item[magic] A text string identifying the Xen version to the guest. \item[nr\_pages] The number of real machine pages available to the guest. \item[shared\_info] Machine address of the shared info structure, allowing the guest to map it during initialisation. \item[flags] Flags for describing optional extra settings to the guest. \item[store\_mfn] Machine address of the Xenstore communications page. \item[store\_evtchn] Event channel to communicate with the store. \item[console\_mfn] Machine address of the console data page. \item[console\_evtchn] Event channel to notify the console backend. \end{description} The boot-only group may only be safely referred to during system boot: \begin{description} \item[pt\_base] Virtual address of the page directory created for us by the domain builder. \item[nr\_pt\_frames] Number of frames used by the builders' bootstrap pagetables. \item[mfn\_list] Virtual address of the list of machine frames this domain owns. \item[mod\_start] Virtual address of any pre-loaded modules (e.g. ramdisk) \item[mod\_len] Size of pre-loaded module (if any). \item[cmd\_line] Kernel command line passed by the domain builder. \end{description} % by Mark Williamson <mark.williamson@cl.cam.ac.uk> \chapter{Event Channels} \label{c:eventchannels} Event channels are the basic primitive provided by Xen for event notifications. An event is the Xen equivalent of a hardware interrupt. They essentially store one bit of information, the event of interest is signalled by transitioning this bit from 0 to 1. Notifications are received by a guest via an upcall from Xen, indicating when an event arrives (setting the bit). Further notifications are masked until the bit is cleared again (therefore, guests must check the value of the bit after re-enabling event delivery to ensure no missed notifications). Event notifications can be masked by setting a flag; this is equivalent to disabling interrupts and can be used to ensure atomicity of certain operations in the guest kernel. \section{Hypercall interface} \hypercall{event\_channel\_op(evtchn\_op\_t *op)} The event channel operation hypercall is used for all operations on event channels / ports. Operations are distinguished by the value of the {\bf cmd} field of the {\bf op} structure. The possible commands are described below: \begin{description} \item[EVTCHNOP\_alloc\_unbound] Allocate a new event channel port, ready to be connected to by a remote domain. \begin{itemize} \item Specified domain must exist. \item A free port must exist in that domain. \end{itemize} Unprivileged domains may only allocate their own ports, privileged domains may also allocate ports in other domains. \item[EVTCHNOP\_bind\_interdomain] Bind an event channel for interdomain communications. \begin{itemize} \item Caller domain must have a free port to bind. \item Remote domain must exist. \item Remote port must be allocated and currently unbound. \item Remote port must be expecting the caller domain as the ``remote''. \end{itemize} \item[EVTCHNOP\_bind\_virq] Allocate a port and bind a VIRQ to it. \begin{itemize} \item Caller domain must have a free port to bind. \item VIRQ must be valid. \item VCPU must exist. \item VIRQ must not currently be bound to an event channel. \end{itemize} \item[EVTCHNOP\_bind\_ipi] Allocate and bind a port for notifying other virtual CPUs. \begin{itemize} \item Caller domain must have a free port to bind. \item VCPU must exist. \end{itemize} \item[EVTCHNOP\_bind\_pirq] Allocate and bind a port to a real IRQ. \begin{itemize} \item Caller domain must have a free port to bind. \item PIRQ must be within the valid range. \item Another binding for this PIRQ must not exist for this domain. \item Caller must have an available port. \end{itemize} \item[EVTCHNOP\_close] Close an event channel (no more events will be received). \begin{itemize} \item Port must be valid (currently allocated). \end{itemize} \item[EVTCHNOP\_send] Send a notification on an event channel attached to a port. \begin{itemize} \item Port must be valid. \item Only valid for Interdomain, IPI or Allocated Unbound ports. \end{itemize} \item[EVTCHNOP\_status] Query the status of a port; what kind of port, whether it is bound, what remote domain is expected, what PIRQ or VIRQ it is bound to, what VCPU will be notified, etc. Unprivileged domains may only query the state of their own ports. Privileged domains may query any port. \item[EVTCHNOP\_bind\_vcpu] Bind event channel to a particular VCPU - receive notification upcalls only on that VCPU. \begin{itemize} \item VCPU must exist. \item Port must be valid. \item Event channel must be either: allocated but unbound, bound to an interdomain event channel, bound to a PIRQ. \end{itemize} \end{description} %% %% grant_tables.tex %% %% Made by Mark Williamson %% Login <mark@maw48> %% \chapter{Grant tables} \label{c:granttables} Xen's grant tables provide a generic mechanism to memory sharing between domains. This shared memory interface underpins the split device drivers for block and network IO. Each domain has its own {\bf grant table}. This is a data structure that is shared with Xen; it allows the domain to tell Xen what kind of permissions other domains have on its pages. Entries in the grant table are identified by {\bf grant references}. A grant reference is an integer, which indexes into the grant table. It acts as a capability which the grantee can use to perform operations on the granter's memory. This capability-based system allows shared-memory communications between unprivileged domains. A grant reference also encapsulates the details of a shared page, removing the need for a domain to know the real machine address of a page it is sharing. This makes it possible to share memory correctly with domains running in fully virtualised memory. \section{Interface} \subsection{Grant table manipulation} Creating and destroying grant references is done by direct access to the grant table. This removes the need to involve Xen when creating grant references, modifying access permissions, etc. The grantee domain will invoke hypercalls to use the grant references. Four main operations can be accomplished by directly manipulating the table: \begin{description} \item[Grant foreign access] allocate a new entry in the grant table and fill out the access permissions accordingly. The access permissions will be looked up by Xen when the grantee attempts to use the reference to map the granted frame. \item[End foreign access] check that the grant reference is not currently in use, then remove the mapping permissions for the frame. This prevents further mappings from taking place but does not allow forced revocations of existing mappings. \item[Grant foreign transfer] allocate a new entry in the table specifying transfer permissions for the grantee. Xen will look up this entry when the grantee attempts to transfer a frame to the granter. \item[End foreign transfer] remove permissions to prevent a transfer occurring in future. If the transfer is already committed, modifying the grant table cannot prevent it from completing. \end{description} \subsection{Hypercalls} Use of grant references is accomplished via a hypercall. The grant table op hypercall takes three arguments: \hypercall{grant\_table\_op(unsigned int cmd, void *uop, unsigned int count)} {\bf cmd} indicates the grant table operation of interest. {\bf uop} is a pointer to a structure (or an array of structures) describing the operation to be performed. The {\bf count} field describes how many grant table operations are being batched together. The core logic is situated in {\bf xen/common/grant\_table.c}. The grant table operation hypercall can be used to perform the following actions: \begin{description} \item[GNTTABOP\_map\_grant\_ref] Given a grant reference from another domain, map the referred page into the caller's address space. \item[GNTTABOP\_unmap\_grant\_ref] Remove a mapping to a granted frame from the caller's address space. This is used to voluntarily relinquish a mapping to a granted page. \item[GNTTABOP\_setup\_table] Setup grant table for caller domain. \item[GNTTABOP\_dump\_table] Debugging operation. \item[GNTTABOP\_transfer] Given a transfer reference from another domain, transfer ownership of a page frame to that domain. \end{description} %% %% xenstore.tex %% %% Made by Mark Williamson %% Login <mark@maw48> %% \chapter{Xenstore} Xenstore is the mechanism by which control-plane activities occur. These activities include: \begin{itemize} \item Setting up shared memory regions and event channels for use with the split device drivers.


context:
space:
mode: