From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-26.3 required=3.0 tests=BAYES_00,DKIMWL_WL_MED, DKIM_SIGNED,DKIM_VALID,DKIM_VALID_AU,HEADER_FROM_DIFFERENT_DOMAINS, INCLUDES_CR_TRAILER,INCLUDES_PATCH,MAILING_LIST_MULTI,SPF_HELO_NONE,SPF_PASS, USER_AGENT_GIT,USER_IN_DEF_DKIM_WL autolearn=unavailable autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id A022CC47434 for ; Tue, 8 Dec 2020 21:37:29 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id 860DC23B23 for ; Tue, 8 Dec 2020 21:37:29 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1730127AbgLHVhY (ORCPT ); Tue, 8 Dec 2020 16:37:24 -0500 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:49788 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1730078AbgLHVhX (ORCPT ); Tue, 8 Dec 2020 16:37:23 -0500 Received: from mail-pg1-x549.google.com (mail-pg1-x549.google.com [IPv6:2607:f8b0:4864:20::549]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 540C3C0611C5 for ; Tue, 8 Dec 2020 13:36:12 -0800 (PST) Received: by mail-pg1-x549.google.com with SMTP id l7so73988pgq.16 for ; Tue, 08 Dec 2020 13:36:12 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=20161025; h=sender:date:in-reply-to:message-id:mime-version:references:subject :from:to:cc; bh=UEByDBKZVfTm3zy0Um+iwW/BbeQm2aD/QnGz0kihyFg=; b=W3NdpQJzPiJZvI/6fFLeodj/HhxNDIAkFPpOhBeJiCCK8Jdz8YDdSjQ8vs13VBQVOG BMyujz8LRlhnQV4SlDwFstUz7qSSiCV7QEOB0Zp0Kn6Eqxj9j2JSoH0Laqk+rzEoYb93 kiD7RZWwUaR2h3vpffnGwZ81F+t030NVz9XoYNeMsxdo0jW4D0GT6sXnJdF2eXn/pEGS a/0aWKRE6iSnMShkHkCFOYyaqb1vkOnP/50B2jxlEgoSoAODV7Y/cnmMPsw3T4q9m1Z1 HnxNU5w2ufkg0GmRW19x5HFMGnKXMsv0QUm1tQv1I8rMSlyYk+ALy1dmdJ2dQKn5A+gg U/Gw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:sender:date:in-reply-to:message-id:mime-version :references:subject:from:to:cc; bh=UEByDBKZVfTm3zy0Um+iwW/BbeQm2aD/QnGz0kihyFg=; b=F67J3EkHd1/sx9YoTk6hBmvt3MMj5L0FROotTl157WxMWfAdvJGICCKsJiu4Eg3RQP x1C/EkpasRV44TtgCIabw8NBAfoC3oeR+ALoVvRV2U6Ev5z8RdjzaIAOsXjQRx4jqSmm MZhFET3VR/xlmL+q0IywpFBfPEiHPxWXOVd/qMUt9gug5Nh0PUTDMjqPusPvzcP2k4gn tbq3eVgusUsXBI3ZAGEMYjxtxJiIUM7QbN81zNhlbZNHSMHcPcoRXotGfrttO94DJbBR TjeK/IFHSO30zzuApFk+vp1B+OeuybhCO1HUluJDsr+YsrWTKIgUYBktZi3YSaG7e6+j NRWw== X-Gm-Message-State: AOAM530osS2+jCfaIBrRQ9jDKX2ZNad562y3LPSLYn+09TOBZl7fyQVy aTofOCZnLCBWlJqHzkNrrFGfMFhYJtoa X-Google-Smtp-Source: ABdhPJzaPgMZEMT9lZlWOcI4nOAwkQ9UrM7pCYKAlU3coXMD/+QoLXKYKRcT4VT/gGDyOTo08ODO6/D8cS5N Sender: "vipinsh via sendgmr" X-Received: from vipinsh.kir.corp.google.com ([2620:0:1008:10:1ea0:b8ff:fe75:b885]) (user=vipinsh job=sendgmr) by 2002:aa7:838b:0:b029:18c:42ad:7721 with SMTP id u11-20020aa7838b0000b029018c42ad7721mr21520922pfm.15.1607463371759; Tue, 08 Dec 2020 13:36:11 -0800 (PST) Date: Tue, 8 Dec 2020 13:35:31 -0800 In-Reply-To: <20201208213531.2626955-1-vipinsh@google.com> Message-Id: <20201208213531.2626955-3-vipinsh@google.com> Mime-Version: 1.0 References: <20201208213531.2626955-1-vipinsh@google.com> X-Mailer: git-send-email 2.29.2.576.ga3fc446d84-goog Subject: [Patch v2 2/2] cgroup: SVM: Encryption IDs cgroup documentation. From: Vipin Sharma To: thomas.lendacky@amd.com, brijesh.singh@amd.com, jon.grimm@amd.com, eric.vantassell@amd.com, pbonzini@redhat.com, seanjc@google.com, tj@kernel.org, lizefan@huawei.com, hannes@cmpxchg.org, frankja@linux.ibm.com, borntraeger@de.ibm.com, corbet@lwn.net Cc: joro@8bytes.org, vkuznets@redhat.com, wanpengli@tencent.com, jmattson@google.com, tglx@linutronix.de, mingo@redhat.com, bp@alien8.de, hpa@zytor.com, gingell@google.com, rientjes@google.com, dionnaglaze@google.com, kvm@vger.kernel.org, x86@kernel.org, cgroups@vger.kernel.org, linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org, Vipin Sharma Content-Type: text/plain; charset="UTF-8" Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Documentation for both cgroup versions, v1 and v2, of Encryption IDs controller. This new controller is used to track and limit usage of hardware memory encryption capabilities on the CPUs. Signed-off-by: Vipin Sharma Reviewed-by: David Rientjes Reviewed-by: Dionna Glaze --- .../admin-guide/cgroup-v1/encryption_ids.rst | 108 ++++++++++++++++++ Documentation/admin-guide/cgroup-v2.rst | 78 ++++++++++++- 2 files changed, 184 insertions(+), 2 deletions(-) create mode 100644 Documentation/admin-guide/cgroup-v1/encryption_ids.rst diff --git a/Documentation/admin-guide/cgroup-v1/encryption_ids.rst b/Documentation/admin-guide/cgroup-v1/encryption_ids.rst new file mode 100644 index 000000000000..891143b4e229 --- /dev/null +++ b/Documentation/admin-guide/cgroup-v1/encryption_ids.rst @@ -0,0 +1,108 @@ +========================= +Encryption IDs Controller +========================= + +Overview +======== +There are multiple hardware memory encryption capabilities provided by the +hardware vendors, like Secure Encrypted Virtualization (SEV) and SEV Encrypted +State (SEV-ES) from AMD. + +These features are being used in encrypting virtual machines (VMs) and user +space programs. However, only a small number of keys/IDs can be used +simultaneously. + +This limited availability of these IDs requires system admin to optimize +allocation, control, and track the usage of the resources in the cloud +infrastructure. This resource also needs to be protected from getting exhausted +by some malicious program and causing starvation for other programs. + +Encryption IDs controller provides capability to register the resource for +controlling and tracking through the cgroups. + +How to Enable Controller +======================== + +- Enable Encryption controller:: + + CONFIG_CGROUP_ENCRYPTION_IDS=y + +- Above options will build Encryption controller support in the kernel. + To mount the Encryption controller:: + + mount -t cgroup -o encryption none /sys/fs/cgroup/encryption + + +Interface Files +=============== +Each encryption ID type have their own interface files, +encryption_id.[ID TYPE].{max, current, stat}, where "ID TYPE" can be sev and +sev-es. + + encryption_ids.[ID TYPE].stat + A read-only flat-keyed single value file. This file exists only in the + root cgroup. + + It shows the total number of encryption IDs available and currently in + use on the platform:: + # cat encryption.sev.stat + total 509 + used 0 + + encryption_ids.[ID TYPE].max + A read-write file which exists on the non-root cgroups. File is used to + set maximum count of "[ID TYPE]" which can be used in the cgroup. + + Limit can be set to max by:: + # echo max > encryption.sev.max + + Limit can be set by:: + # echo 100 > encryption.sev.max + + This file shows the max limit of the encryption ID in the cgroup:: + # cat encryption.sev.max + max + + OR:: + # cat encryption.sev.max + 100 + + Limits can be set more than the "total" capacity value in the + encryption_ids.[ID TYPE].stat file, however, the controller ensures + that the usage never exceeds the "total" and the max limit. + + encryption_ids.[ID TYPE].current + A read-only single value file which exists on non-root cgroups. + + Shows the total number of encrypted IDs being used in the cgroup. + +Hierarchy +========= + +Encryption IDs controller supports hierarchical accounting. It supports +following features: + +1. Current usage in the cgroup shows IDs used in the cgroup and its descendent cgroups. +2. Current usage can never exceed the corresponding max limit set in the cgroup + and its ancestor's chain up to the root. + +Suppose the following example hierarchy:: + + root + / \ + A B + | + C + +1. A will show the count of IDs used in A and C. +2. C's current IDs usage may not exceed any of the max limits set in C, A, or + root. + +Migration and ownership +======================= + +An encryption ID is charged to the cgroup in which it is used first, and +stays charged to that cgroup until that ID is freed. Migrating a process +to a different cgroup do not move the charge to the destination cgroup +where the process has moved. + diff --git a/Documentation/admin-guide/cgroup-v2.rst b/Documentation/admin-guide/cgroup-v2.rst index 608d7c279396..7938bb7c6e1c 100644 --- a/Documentation/admin-guide/cgroup-v2.rst +++ b/Documentation/admin-guide/cgroup-v2.rst @@ -63,8 +63,11 @@ v1 is available under :ref:`Documentation/admin-guide/cgroup-v1/index.rst encryption.sev.max + + Limit can be set by:: + # echo 100 > encryption.sev.max + + This file shows the max limit of the encryption ID in the cgroup:: + # cat encryption.sev.max + max + + OR:: + # cat encryption.sev.max + 100 + + Limits can be set more than the "total" capacity value in the + encryption_ids.[ID TYPE].stat file, however, the controller ensures + that the usage never exceeds the "total" and the max limit. + + encryption_ids.[ID TYPE].current + A read-only single value file which exists on non-root cgroups. + + Shows the total number of encrypted IDs being used in the cgroup. + +Migration and Ownership +~~~~~~~~~~~~~~~~~~~~~~~ + +An encryption ID is charged to the cgroup in which it is used first, and +stays charged to that cgroup until that ID is freed. Migrating a process +to a different cgroup do not move the charge to the destination cgroup +where the process has moved. + Misc ---- -- 2.29.2.576.ga3fc446d84-goog