Daniel P. Berrangé | 336a745 | 2019-08-23 17:09:24 +0100 | [diff] [blame] | 1 | =========== |
| 2 | QEMU README |
| 3 | =========== |
bellard | 3ef693a | 2003-03-23 20:17:16 +0000 | [diff] [blame] | 4 | |
Daniel P. Berrange | 0a3c190 | 2015-10-12 18:41:19 +0100 | [diff] [blame] | 5 | QEMU is a generic and open source machine & userspace emulator and |
| 6 | virtualizer. |
| 7 | |
| 8 | QEMU is capable of emulating a complete machine in software without any |
| 9 | need for hardware virtualization support. By using dynamic translation, |
| 10 | it achieves very good performance. QEMU can also integrate with the Xen |
| 11 | and KVM hypervisors to provide emulated hardware while allowing the |
| 12 | hypervisor to manage the CPU. With hypervisor support, QEMU can achieve |
| 13 | near native performance for CPUs. When QEMU emulates CPUs directly it is |
| 14 | capable of running operating systems made for one machine (e.g. an ARMv7 |
| 15 | board) on a different machine (e.g. an x86_64 PC board). |
| 16 | |
| 17 | QEMU is also capable of providing userspace API virtualization for Linux |
| 18 | and BSD kernel interfaces. This allows binaries compiled against one |
| 19 | architecture ABI (e.g. the Linux PPC64 ABI) to be run on a host using a |
| 20 | different architecture ABI (e.g. the Linux x86_64 ABI). This does not |
| 21 | involve any hardware emulation, simply CPU and syscall emulation. |
| 22 | |
| 23 | QEMU aims to fit into a variety of use cases. It can be invoked directly |
| 24 | by users wishing to have full control over its behaviour and settings. |
| 25 | It also aims to facilitate integration into higher level management |
| 26 | layers, by providing a stable command line interface and monitor API. |
| 27 | It is commonly invoked indirectly via the libvirt library when using |
| 28 | open source applications such as oVirt, OpenStack and virt-manager. |
| 29 | |
| 30 | QEMU as a whole is released under the GNU General Public License, |
| 31 | version 2. For full licensing details, consult the LICENSE file. |
| 32 | |
| 33 | |
| 34 | Building |
Pranith Kumar | b95aae1 | 2016-07-20 16:31:29 -0400 | [diff] [blame] | 35 | ======== |
Daniel P. Berrange | 0a3c190 | 2015-10-12 18:41:19 +0100 | [diff] [blame] | 36 | |
| 37 | QEMU is multi-platform software intended to be buildable on all modern |
| 38 | Linux platforms, OS-X, Win32 (via the Mingw64 toolchain) and a variety |
| 39 | of other UNIX targets. The simple steps to build QEMU are: |
| 40 | |
Daniel P. Berrangé | 336a745 | 2019-08-23 17:09:24 +0100 | [diff] [blame] | 41 | |
| 42 | .. code-block:: shell |
| 43 | |
Pranith Kumar | b95aae1 | 2016-07-20 16:31:29 -0400 | [diff] [blame] | 44 | mkdir build |
| 45 | cd build |
| 46 | ../configure |
| 47 | make |
Daniel P. Berrange | 0a3c190 | 2015-10-12 18:41:19 +0100 | [diff] [blame] | 48 | |
Daniel P. Berrange | 0a3c190 | 2015-10-12 18:41:19 +0100 | [diff] [blame] | 49 | Additional information can also be found online via the QEMU website: |
| 50 | |
Daniel P. Berrangé | 336a745 | 2019-08-23 17:09:24 +0100 | [diff] [blame] | 51 | * `<https://qemu.org/Hosts/Linux>`_ |
| 52 | * `<https://qemu.org/Hosts/Mac>`_ |
| 53 | * `<https://qemu.org/Hosts/W32>`_ |
Daniel P. Berrange | 0a3c190 | 2015-10-12 18:41:19 +0100 | [diff] [blame] | 54 | |
| 55 | |
| 56 | Submitting patches |
Pranith Kumar | b95aae1 | 2016-07-20 16:31:29 -0400 | [diff] [blame] | 57 | ================== |
Daniel P. Berrange | 0a3c190 | 2015-10-12 18:41:19 +0100 | [diff] [blame] | 58 | |
| 59 | The QEMU source code is maintained under the GIT version control system. |
| 60 | |
Daniel P. Berrangé | 336a745 | 2019-08-23 17:09:24 +0100 | [diff] [blame] | 61 | .. code-block:: shell |
| 62 | |
Stefan Hajnoczi | c814b17 | 2018-11-08 11:15:24 +0000 | [diff] [blame] | 63 | git clone https://git.qemu.org/git/qemu.git |
Daniel P. Berrange | 0a3c190 | 2015-10-12 18:41:19 +0100 | [diff] [blame] | 64 | |
Fam Zheng | 23500c6 | 2018-02-26 11:03:26 +0800 | [diff] [blame] | 65 | When submitting patches, one common approach is to use 'git |
Daniel P. Berrange | 0a3c190 | 2015-10-12 18:41:19 +0100 | [diff] [blame] | 66 | format-patch' and/or 'git send-email' to format & send the mail to the |
| 67 | qemu-devel@nongnu.org mailing list. All patches submitted must contain |
| 68 | a 'Signed-off-by' line from the author. Patches should follow the |
Daniel P. Berrangé | 637f395 | 2019-08-23 17:12:05 +0100 | [diff] [blame] | 69 | guidelines set out in the CODING_STYLE.rst file. |
Daniel P. Berrange | 0a3c190 | 2015-10-12 18:41:19 +0100 | [diff] [blame] | 70 | |
| 71 | Additional information on submitting patches can be found online via |
| 72 | the QEMU website |
| 73 | |
Daniel P. Berrangé | 336a745 | 2019-08-23 17:09:24 +0100 | [diff] [blame] | 74 | * `<https://qemu.org/Contribute/SubmitAPatch>`_ |
| 75 | * `<https://qemu.org/Contribute/TrivialPatches>`_ |
Daniel P. Berrange | 0a3c190 | 2015-10-12 18:41:19 +0100 | [diff] [blame] | 76 | |
Eric Blake | a348f64 | 2017-11-29 09:25:10 -0600 | [diff] [blame] | 77 | The QEMU website is also maintained under source control. |
| 78 | |
Daniel P. Berrangé | 336a745 | 2019-08-23 17:09:24 +0100 | [diff] [blame] | 79 | .. code-block:: shell |
| 80 | |
Stefan Hajnoczi | c814b17 | 2018-11-08 11:15:24 +0000 | [diff] [blame] | 81 | git clone https://git.qemu.org/git/qemu-web.git |
Daniel P. Berrangé | 336a745 | 2019-08-23 17:09:24 +0100 | [diff] [blame] | 82 | |
| 83 | * `<https://www.qemu.org/2017/02/04/the-new-qemu-website-is-up/>`_ |
Daniel P. Berrange | 0a3c190 | 2015-10-12 18:41:19 +0100 | [diff] [blame] | 84 | |
Fam Zheng | 7c9e274 | 2018-03-06 10:43:28 +0800 | [diff] [blame] | 85 | A 'git-publish' utility was created to make above process less |
Fam Zheng | 23500c6 | 2018-02-26 11:03:26 +0800 | [diff] [blame] | 86 | cumbersome, and is highly recommended for making regular contributions, |
| 87 | or even just for sending consecutive patch series revisions. It also |
| 88 | requires a working 'git send-email' setup, and by default doesn't |
| 89 | automate everything, so you may want to go through the above steps |
| 90 | manually for once. |
| 91 | |
| 92 | For installation instructions, please go to |
| 93 | |
Daniel P. Berrangé | 336a745 | 2019-08-23 17:09:24 +0100 | [diff] [blame] | 94 | * `<https://github.com/stefanha/git-publish>`_ |
Fam Zheng | 23500c6 | 2018-02-26 11:03:26 +0800 | [diff] [blame] | 95 | |
| 96 | The workflow with 'git-publish' is: |
| 97 | |
Daniel P. Berrangé | 336a745 | 2019-08-23 17:09:24 +0100 | [diff] [blame] | 98 | .. code-block:: shell |
| 99 | |
Fam Zheng | 23500c6 | 2018-02-26 11:03:26 +0800 | [diff] [blame] | 100 | $ git checkout master -b my-feature |
| 101 | $ # work on new commits, add your 'Signed-off-by' lines to each |
| 102 | $ git publish |
| 103 | |
| 104 | Your patch series will be sent and tagged as my-feature-v1 if you need to refer |
| 105 | back to it in the future. |
| 106 | |
| 107 | Sending v2: |
| 108 | |
Daniel P. Berrangé | 336a745 | 2019-08-23 17:09:24 +0100 | [diff] [blame] | 109 | .. code-block:: shell |
| 110 | |
Fam Zheng | 23500c6 | 2018-02-26 11:03:26 +0800 | [diff] [blame] | 111 | $ git checkout my-feature # same topic branch |
| 112 | $ # making changes to the commits (using 'git rebase', for example) |
| 113 | $ git publish |
| 114 | |
| 115 | Your patch series will be sent with 'v2' tag in the subject and the git tip |
| 116 | will be tagged as my-feature-v2. |
| 117 | |
Daniel P. Berrange | 0a3c190 | 2015-10-12 18:41:19 +0100 | [diff] [blame] | 118 | Bug reporting |
Pranith Kumar | b95aae1 | 2016-07-20 16:31:29 -0400 | [diff] [blame] | 119 | ============= |
Daniel P. Berrange | 0a3c190 | 2015-10-12 18:41:19 +0100 | [diff] [blame] | 120 | |
| 121 | The QEMU project uses Launchpad as its primary upstream bug tracker. Bugs |
| 122 | found when running code built from QEMU git or upstream released sources |
| 123 | should be reported via: |
| 124 | |
Daniel P. Berrangé | 336a745 | 2019-08-23 17:09:24 +0100 | [diff] [blame] | 125 | * `<https://bugs.launchpad.net/qemu/>`_ |
Daniel P. Berrange | 0a3c190 | 2015-10-12 18:41:19 +0100 | [diff] [blame] | 126 | |
| 127 | If using QEMU via an operating system vendor pre-built binary package, it |
| 128 | is preferable to report bugs to the vendor's own bug tracker first. If |
| 129 | the bug is also known to affect latest upstream code, it can also be |
| 130 | reported via launchpad. |
| 131 | |
| 132 | For additional information on bug reporting consult: |
| 133 | |
Daniel P. Berrangé | 336a745 | 2019-08-23 17:09:24 +0100 | [diff] [blame] | 134 | * `<https://qemu.org/Contribute/ReportABug>`_ |
Daniel P. Berrange | 0a3c190 | 2015-10-12 18:41:19 +0100 | [diff] [blame] | 135 | |
| 136 | |
| 137 | Contact |
Pranith Kumar | b95aae1 | 2016-07-20 16:31:29 -0400 | [diff] [blame] | 138 | ======= |
Daniel P. Berrange | 0a3c190 | 2015-10-12 18:41:19 +0100 | [diff] [blame] | 139 | |
| 140 | The QEMU community can be contacted in a number of ways, with the two |
| 141 | main methods being email and IRC |
| 142 | |
Daniel P. Berrangé | 336a745 | 2019-08-23 17:09:24 +0100 | [diff] [blame] | 143 | * `<mailto:qemu-devel@nongnu.org>`_ |
| 144 | * `<https://lists.nongnu.org/mailman/listinfo/qemu-devel>`_ |
| 145 | * #qemu on irc.oftc.net |
Daniel P. Berrange | 0a3c190 | 2015-10-12 18:41:19 +0100 | [diff] [blame] | 146 | |
| 147 | Information on additional methods of contacting the community can be |
| 148 | found online via the QEMU website: |
| 149 | |
Daniel P. Berrangé | 336a745 | 2019-08-23 17:09:24 +0100 | [diff] [blame] | 150 | * `<https://qemu.org/Contribute/StartHere>`_ |