From patchwork Mon Apr 8 11:09:43 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: George Dunlap X-Patchwork-Id: 10889315 Return-Path: Received: from mail.wl.linuxfoundation.org (pdx-wl-mail.web.codeaurora.org [172.30.200.125]) by pdx-korg-patchwork-2.web.codeaurora.org (Postfix) with ESMTP id 80990922 for ; Mon, 8 Apr 2019 11:12:24 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 642F3284AF for ; Mon, 8 Apr 2019 11:12:24 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id 5408A2863C; Mon, 8 Apr 2019 11:12:24 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on pdx-wl-mail.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-5.2 required=2.0 tests=BAYES_00,MAILING_LIST_MULTI, RCVD_IN_DNSWL_MED autolearn=ham version=3.3.1 Received: from lists.xenproject.org (lists.xenproject.org [192.237.175.120]) (using TLSv1.2 with cipher AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mail.wl.linuxfoundation.org (Postfix) with ESMTPS id AA7C5284AF for ; Mon, 8 Apr 2019 11:12:23 +0000 (UTC) Received: from localhost ([127.0.0.1] helo=lists.xenproject.org) by lists.xenproject.org with esmtp (Exim 4.89) (envelope-from ) id 1hDSAG-0001XF-8K; Mon, 08 Apr 2019 11:10:12 +0000 Received: from us1-rack-dfw2.inumbo.com ([104.130.134.6]) by lists.xenproject.org with esmtp (Exim 4.89) (envelope-from ) id 1hDSAE-0001XA-KL for xen-devel@lists.xenproject.org; Mon, 08 Apr 2019 11:10:10 +0000 X-Inumbo-ID: dee25549-59ee-11e9-92d7-bc764e045a96 Received: from SMTP03.CITRIX.COM (unknown [162.221.156.55]) by us1-rack-dfw2.inumbo.com (Halon) with ESMTPS id dee25549-59ee-11e9-92d7-bc764e045a96; Mon, 08 Apr 2019 11:10:09 +0000 (UTC) X-IronPort-AV: E=Sophos;i="5.60,325,1549929600"; d="scan'208";a="82990361" From: George Dunlap To: Date: Mon, 8 Apr 2019 12:09:43 +0100 Message-ID: <20190408110943.8987-1-george.dunlap@citrix.com> X-Mailer: git-send-email 2.20.1 MIME-Version: 1.0 Subject: [Xen-devel] [PATCH v2] docs/xl: Clarify documentation for mem-max and mem-set X-BeenThere: xen-devel@lists.xenproject.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: Xen developer discussion List-Unsubscribe: , List-Post: List-Help: List-Subscribe: , Cc: Lars Kurth , Stefano Stabellini , Wei Liu , Konrad Wilk , Andrew Cooper , Tim Deegan , George Dunlap , Julien Grall , Jan Beulich , Ian Jackson Errors-To: xen-devel-bounces@lists.xenproject.org Sender: "Xen-devel" X-Virus-Scanned: ClamAV using ClamSMTP mem-set is the primary command that users will need to use and understand. Move it first, and clarify the wording; also specify that you can't set the target higher than maxmem from the domain config. mem-max is actually a pretty useless command at the moment. Clarify that users are not expected to use it; and document all of its quirky behavior. Signed-off-by: George Dunlap Acked-by: Wei Liu --- v2: - Reword memory unit section based on review feedback I'm actully somewhat tempted to take out the entry for mem-max entirely -- it's not at all clear to me what anyone would use it for, and it's only likely to confuse people. CC: Ian Jackson CC: Wei Liu CC: Andrew Cooper CC: Jan Beulich CC: Tim Deegan CC: Konrad Wilk CC: Stefano Stabellini CC: Julien Grall CC: Lars Kurth --- docs/man/xl.1.pod.in | 75 +++++++++++++++++++++++++++++++------------- 1 file changed, 53 insertions(+), 22 deletions(-) diff --git a/docs/man/xl.1.pod.in b/docs/man/xl.1.pod.in index 4310fcd818..f44f054dfb 100644 --- a/docs/man/xl.1.pod.in +++ b/docs/man/xl.1.pod.in @@ -393,40 +393,71 @@ less utilized than a high CPU workload. Consider yourself warned. =back -=item B I I +=item B I I -Specify the maximum amount of memory the domain is able to use, appending 't' -for terabytes, 'g' for gigabytes, 'm' for megabytes, 'k' for kilobytes and 'b' -for bytes. +Set the target for the domain's balloon driver. -The mem-max value may not correspond to the actual memory used in the -domain, as it may balloon down its memory to give more back to the OS. +The default unit is kiB. Add 't' for TiB, 'g' for GiB, 'm' for +MiB, 'k' for kiB, and 'b' for bytes (e.g., `2048m` for 2048 MiB). -The value given just sets the memory amount the domain is allowed to allocate -in the hypervisor. It can't be set lower than the current reservation, but -it is allowed to be higher than the configured maximum memory size of the -domain (B parameter in the domain's configuration). Using B -to set the maximum memory above the initial B value will not allow the -additional memory to be used via B. The initial B value is -still used as an upper limit for B. +This must be less than the initial B parameter in the domain's +configuration. -The domain will not receive any signal regarding the changed memory limit. +Note that this operation requests the guest operating system's balloon +driver to reach the target amount of memory. The guest may fail to +reach that amount of memory for any number of reasons, including: -=item B I I +=over 4 + +=item + +The guest doesn't have a balloon driver installed + +=item + +The guest's balloon driver is buggy + +=item + +The guest's balloon driver cannot create free guest memory due to +guest memory pressure + +=item -Set the domain's used memory using the balloon driver; append 't' for -terabytes, 'g' for gigabytes, 'm' for megabytes, 'k' for kilobytes and 'b' for -bytes. +The guest's balloon driver cannot allocate memory from Xen because of +hypervisor memory pressure -Because this operation requires cooperation from the domain operating -system, there is no guarantee that it will succeed. This command will -definitely not work unless the domain has the required paravirt -driver. +=item + +The guest administrator has disabled the balloon driver + +=back B There is no good way to know in advance how small of a mem-set will make a domain unstable and cause it to crash. Be very careful when using this command on running domains. +=item B I I + +Specify the limit Xen will place on the amount of memory a guest may +allocate. + +The default unit is kiB. Add 't' for TiB, 'g' for GiB, 'm' for +MiB, 'k' for kiB, and 'b' for bytes (e.g., `2048m` for 2048 MiB). + +NB that users normally shouldn't need this command; B will +set this as appropriate automatically. + +I can't be set lower than the current memory target for +I. It is allowed to be higher than the configured maximum +memory size of the domain (B parameter in the domain's +configuration). Note however that the initial B value is still +used as an upper limit for B. Also note that calling B will reset this value. + +The domain will not receive any signal regarding the changed memory +limit. + =item B [I] I I Migrate a domain to another host machine. By default B relies on ssh as a