diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/libcacard.txt | 4 | ||||
| -rw-r--r-- | docs/multiseat.txt | 2 | ||||
| -rw-r--r-- | docs/qapi-code-gen.txt | 53 | ||||
| -rw-r--r-- | docs/qcow2-cache.txt | 164 | ||||
| -rw-r--r-- | docs/specs/ppc-spapr-hcalls.txt | 4 | ||||
| -rw-r--r-- | docs/specs/qcow2.txt | 2 | ||||
| -rw-r--r-- | docs/specs/rocker.txt | 2 | ||||
| -rw-r--r-- | docs/writing-qmp-commands.txt | 2 |
8 files changed, 196 insertions, 37 deletions
diff --git a/docs/libcacard.txt b/docs/libcacard.txt index 8db421d3a9..499cf7d79c 100644 --- a/docs/libcacard.txt +++ b/docs/libcacard.txt @@ -327,7 +327,7 @@ and applet. int vcard_emul_get_login_count(VCard *card); - This function returns the the number of remaining login attempts for this + This function returns the number of remaining login attempts for this card. If the card emulator does not know, or the card does not have a way of giving this information, this function returns -1. @@ -421,7 +421,7 @@ functions: The vcard is the value returned from vcard_new. The type is the card type emulator that this card should presented to the guest as. The flags are card type emulator specific options. The certs, - cert_len, and keys are all arrays of length cert_count. These are the + cert_len, and keys are all arrays of length cert_count. These are the same of the parameters xxxx_card_init() accepts. Finally the card is associated with its reader by the call: diff --git a/docs/multiseat.txt b/docs/multiseat.txt index ebf2446933..807518c8af 100644 --- a/docs/multiseat.txt +++ b/docs/multiseat.txt @@ -135,7 +135,7 @@ configuration: TAG+="seat", ENV{ID_AUTOSEAT}="1" Patch with this rule has been submitted to upstream udev/systemd, was -accepted and and should be included in the next systemd release (222). +accepted and should be included in the next systemd release (222). So, if your guest has this or a newer version, multiseat will work just fine without any manual guest configuration. diff --git a/docs/qapi-code-gen.txt b/docs/qapi-code-gen.txt index 61b5be47fb..ff16df2456 100644 --- a/docs/qapi-code-gen.txt +++ b/docs/qapi-code-gen.txt @@ -163,7 +163,7 @@ The QAPI schema definitions can be modularized using the 'include' directive: The directive is evaluated recursively, and include paths are relative to the file using the directive. Multiple includes of the same file are -safe. No other keys should appear in the expression, and the include +idempotent. No other keys should appear in the expression, and the include value should be a string. As a matter of style, it is a good idea to have all files be @@ -300,7 +300,6 @@ an implicit C enum 'NameKind' is created, corresponding to the union the union can be named 'max', as this would collide with the implicit enum. The value for each branch can be of any type. - A flat union definition specifies a struct as its base, and avoids nesting on the wire. All branches of the union must be complex types, and the top-level fields of the union dictionary on @@ -314,7 +313,7 @@ adding a common field 'readonly', renaming the discriminator to something more applicable, and reducing the number of {} required on the wire: - { 'enum': 'BlockdevDriver', 'data': [ 'raw', 'qcow2' ] } + { 'enum': 'BlockdevDriver', 'data': [ 'file', 'qcow2' ] } { 'struct': 'BlockdevCommonOptions', 'data': { 'driver': 'BlockdevDriver', 'readonly': 'bool' } } { 'union': 'BlockdevOptions', @@ -350,7 +349,7 @@ is identical on the wire to: { 'struct': 'Base', 'data': { 'type': 'Enum' } } { 'struct': 'Branch1', 'data': { 'data': 'str' } } { 'struct': 'Branch2', 'data': { 'data': 'int' } } - { 'union': 'Flat': 'base': 'Base', 'discriminator': 'type', + { 'union': 'Flat', 'base': 'Base', 'discriminator': 'type', 'data': { 'one': 'Branch1', 'two': 'Branch2' } } @@ -394,7 +393,7 @@ following example objects: === Commands === Usage: { 'command': STRING, '*data': COMPLEX-TYPE-NAME-OR-DICT, - '*returns': TYPE-NAME-OR-DICT, + '*returns': TYPE-NAME, '*gen': false, '*success-response': false } Commands are defined by using a dictionary containing several members, @@ -405,10 +404,9 @@ Client JSON Protocol command exchange. The 'data' argument maps to the "arguments" dictionary passed in as part of a Client JSON Protocol command. The 'data' member is optional and defaults to {} (an empty dictionary). If present, it must be the -string name of a complex type, a one-element array containing the name -of a complex type, or a dictionary that declares an anonymous type -with the same semantics as a 'struct' expression, with one exception -noted below when 'gen' is used. +string name of a complex type, or a dictionary that declares an +anonymous type with the same semantics as a 'struct' expression, with +one exception noted below when 'gen' is used. The 'returns' member describes what will appear in the "return" field of a Client JSON Protocol reply on successful completion of a command. @@ -416,14 +414,13 @@ The member is optional from the command declaration; if absent, the "return" field will be an empty dictionary. If 'returns' is present, it must be the string name of a complex or built-in type, a one-element array containing the name of a complex or built-in type, -or a dictionary that declares an anonymous type with the same -semantics as a 'struct' expression, with one exception noted below -when 'gen' is used. Although it is permitted to have the 'returns' -member name a built-in type or an array of built-in types, any command -that does this cannot be extended to return additional information in -the future; thus, new commands should strongly consider returning a -dictionary-based type or an array of dictionaries, even if the -dictionary only contains one field at the present. +with one exception noted below when 'gen' is used. Although it is +permitted to have the 'returns' member name a built-in type or an +array of built-in types, any command that does this cannot be extended +to return additional information in the future; thus, new commands +should strongly consider returning a dictionary-based type or an array +of dictionaries, even if the dictionary only contains one field at the +present. All commands in Client JSON Protocol use a dictionary to report failure, with no way to specify that in QAPI. Where the error return @@ -555,6 +552,7 @@ Example: qapi_dealloc_visitor_cleanup(md); } + void qapi_free_UserDefOne(UserDefOne *obj) { QapiDeallocVisitor *md; @@ -569,7 +567,6 @@ Example: visit_type_UserDefOne(v, &obj, NULL, NULL); qapi_dealloc_visitor_cleanup(md); } - $ cat qapi-generated/example-qapi-types.h [Uninteresting stuff omitted...] @@ -580,8 +577,7 @@ Example: typedef struct UserDefOne UserDefOne; - typedef struct UserDefOneList - { + typedef struct UserDefOneList { union { UserDefOne *value; uint64_t padding; @@ -589,10 +585,10 @@ Example: struct UserDefOneList *next; } UserDefOneList; + [Functions on built-in types omitted...] - struct UserDefOne - { + struct UserDefOne { int64_t integer; char *string; }; @@ -630,6 +626,7 @@ Example: static void visit_type_UserDefOne_fields(Visitor *m, UserDefOne **obj, Error **errp) { Error *err = NULL; + visit_type_int(m, &(*obj)->integer, "integer", &err); if (err) { goto out; @@ -743,7 +740,7 @@ Example: static void qmp_marshal_input_my_command(QDict *args, QObject **ret, Error **errp) { Error *local_err = NULL; - UserDefOne *retval = NULL; + UserDefOne *retval; QmpInputVisitor *mi = qmp_input_visitor_new_strict(QOBJECT(args)); QapiDeallocVisitor *md; Visitor *v; @@ -769,7 +766,6 @@ Example: v = qapi_dealloc_get_visitor(md); visit_type_UserDefOne(v, &arg1, "arg1", NULL); qapi_dealloc_visitor_cleanup(md); - return; } static void qmp_init_marshal(void) @@ -826,7 +822,7 @@ Example: QDECREF(qmp); } - const char *EXAMPLE_QAPIEvent_lookup[] = { + const char *example_QAPIEvent_lookup[] = { "MY_EVENT", NULL, }; @@ -843,11 +839,10 @@ Example: void qapi_event_send_my_event(Error **errp); - extern const char *EXAMPLE_QAPIEvent_lookup[]; - typedef enum EXAMPLE_QAPIEvent - { + extern const char *example_QAPIEvent_lookup[]; + typedef enum example_QAPIEvent { EXAMPLE_QAPI_EVENT_MY_EVENT = 0, EXAMPLE_QAPI_EVENT_MAX = 1, - } EXAMPLE_QAPIEvent; + } example_QAPIEvent; #endif diff --git a/docs/qcow2-cache.txt b/docs/qcow2-cache.txt new file mode 100644 index 0000000000..5bb06072d3 --- /dev/null +++ b/docs/qcow2-cache.txt @@ -0,0 +1,164 @@ +qcow2 L2/refcount cache configuration +===================================== +Copyright (C) 2015 Igalia, S.L. +Author: Alberto Garcia <berto@igalia.com> + +This work is licensed under the terms of the GNU GPL, version 2 or +later. See the COPYING file in the top-level directory. + +Introduction +------------ +The QEMU qcow2 driver has two caches that can improve the I/O +performance significantly. However, setting the right cache sizes is +not a straightforward operation. + +This document attempts to give an overview of the L2 and refcount +caches, and how to configure them. + +Please refer to the docs/specs/qcow2.txt file for an in-depth +technical description of the qcow2 file format. + + +Clusters +-------- +A qcow2 file is organized in units of constant size called clusters. + +The cluster size is configurable, but it must be a power of two and +its value 512 bytes or higher. QEMU currently defaults to 64 KB +clusters, and it does not support sizes larger than 2MB. + +The 'qemu-img create' command supports specifying the size using the +cluster_size option: + + qemu-img create -f qcow2 -o cluster_size=128K hd.qcow2 4G + + +The L2 tables +------------- +The qcow2 format uses a two-level structure to map the virtual disk as +seen by the guest to the disk image in the host. These structures are +called the L1 and L2 tables. + +There is one single L1 table per disk image. The table is small and is +always kept in memory. + +There can be many L2 tables, depending on how much space has been +allocated in the image. Each table is one cluster in size. In order to +read or write data from the virtual disk, QEMU needs to read its +corresponding L2 table to find out where that data is located. Since +reading the table for each I/O operation can be expensive, QEMU keeps +an L2 cache in memory to speed up disk access. + +The size of the L2 cache can be configured, and setting the right +value can improve the I/O performance significantly. + + +The refcount blocks +------------------- +The qcow2 format also mantains a reference count for each cluster. +Reference counts are used for cluster allocation and internal +snapshots. The data is stored in a two-level structure similar to the +L1/L2 tables described above. + +The second level structures are called refcount blocks, are also one +cluster in size and the number is also variable and dependent on the +amount of allocated space. + +Each block contains a number of refcount entries. Their size (in bits) +is a power of two and must not be higher than 64. It defaults to 16 +bits, but a different value can be set using the refcount_bits option: + + qemu-img create -f qcow2 -o refcount_bits=8 hd.qcow2 4G + +QEMU keeps a refcount cache to speed up I/O much like the +aforementioned L2 cache, and its size can also be configured. + + +Choosing the right cache sizes +------------------------------ +In order to choose the cache sizes we need to know how they relate to +the amount of allocated space. + +The amount of virtual disk that can be mapped by the L2 and refcount +caches (in bytes) is: + + disk_size = l2_cache_size * cluster_size / 8 + disk_size = refcount_cache_size * cluster_size * 8 / refcount_bits + +With the default values for cluster_size (64KB) and refcount_bits +(16), that is + + disk_size = l2_cache_size * 8192 + disk_size = refcount_cache_size * 32768 + +So in order to cover n GB of disk space with the default values we +need: + + l2_cache_size = disk_size_GB * 131072 + refcount_cache_size = disk_size_GB * 32768 + +QEMU has a default L2 cache of 1MB (1048576 bytes) and a refcount +cache of 256KB (262144 bytes), so using the formulas we've just seen +we have + + 1048576 / 131072 = 8 GB of virtual disk covered by that cache + 262144 / 32768 = 8 GB + + +How to configure the cache sizes +-------------------------------- +Cache sizes can be configured using the -drive option in the +command-line, or the 'blockdev-add' QMP command. + +There are three options available, and all of them take bytes: + +"l2-cache-size": maximum size of the L2 table cache +"refcount-cache-size": maximum size of the refcount block cache +"cache-size": maximum size of both caches combined + +There are two things that need to be taken into account: + + - Both caches must have a size that is a multiple of the cluster + size. + + - If you only set one of the options above, QEMU will automatically + adjust the others so that the L2 cache is 4 times bigger than the + refcount cache. + +This means that these options are equivalent: + + -drive file=hd.qcow2,l2-cache-size=2097152 + -drive file=hd.qcow2,refcount-cache-size=524288 + -drive file=hd.qcow2,cache-size=2621440 + +The reason for this 1/4 ratio is to ensure that both caches cover the +same amount of disk space. Note however that this is only valid with +the default value of refcount_bits (16). If you are using a different +value you might want to calculate both cache sizes yourself since QEMU +will always use the same 1/4 ratio. + +It's also worth mentioning that there's no strict need for both caches +to cover the same amount of disk space. The refcount cache is used +much less often than the L2 cache, so it's perfectly reasonable to +keep it small. + + +Reducing the memory usage +------------------------- +It is possible to clean unused cache entries in order to reduce the +memory usage during periods of low I/O activity. + +The parameter "cache-clean-interval" defines an interval (in seconds). +All cache entries that haven't been accessed during that interval are +removed from memory. + +This example removes all unused cache entries every 15 minutes: + + -drive file=hd.qcow2,cache-clean-interval=900 + +If unset, the default value for this parameter is 0 and it disables +this feature. + +Note that this functionality currently relies on the MADV_DONTNEED +argument for madvise() to actually free the memory, so it is not +useful in systems that don't follow that behavior. diff --git a/docs/specs/ppc-spapr-hcalls.txt b/docs/specs/ppc-spapr-hcalls.txt index 667b3fa00e..5bd8eab78f 100644 --- a/docs/specs/ppc-spapr-hcalls.txt +++ b/docs/specs/ppc-spapr-hcalls.txt @@ -41,8 +41,8 @@ When the guest runs in "real mode" (in powerpc lingua this means with MMU disabled, ie guest effective == guest physical), it only has access to a subset of memory and no IOs. -PAPR provides a set of hypervisor calls to perform cachable or -non-cachable accesses to any guest physical addresses that the +PAPR provides a set of hypervisor calls to perform cacheable or +non-cacheable accesses to any guest physical addresses that the guest can use in order to access IO devices while in real mode. This is typically used by the firmware running in the guest. diff --git a/docs/specs/qcow2.txt b/docs/specs/qcow2.txt index 121dfc8cc1..f236d8c6d9 100644 --- a/docs/specs/qcow2.txt +++ b/docs/specs/qcow2.txt @@ -257,7 +257,7 @@ L2 table entry: 63: 0 for a cluster that is unused or requires COW, 1 if its refcount is exactly one. This information is only accurate - in L2 tables that are reachable from the the active L1 + in L2 tables that are reachable from the active L1 table. Standard Cluster Descriptor: diff --git a/docs/specs/rocker.txt b/docs/specs/rocker.txt index 1c743515c1..d2a82624f4 100644 --- a/docs/specs/rocker.txt +++ b/docs/specs/rocker.txt @@ -297,7 +297,7 @@ but not fired. If only partial credits are returned, the interrupt remains masked but the device generates an interrupt, signaling the driver that more outstanding work is available. -(* this masking is unrelated to to the MSI-X interrupt mask register) +(* this masking is unrelated to the MSI-X interrupt mask register) Endianness ---------- diff --git a/docs/writing-qmp-commands.txt b/docs/writing-qmp-commands.txt index ab1fdd36b4..f7693ca267 100644 --- a/docs/writing-qmp-commands.txt +++ b/docs/writing-qmp-commands.txt @@ -122,7 +122,7 @@ There are a few things to be noticed: Now a little hack is needed. As we're still using the old QMP server we need to add the new command to its internal dispatch table. This step won't be required in the near future. Open the qmp-commands.hx file and add the -following in the botton: +following at the bottom: { .name = "hello-world", |