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.6 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 AA6A4C433E6 for ; Fri, 8 Jan 2021 01:30:36 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id 87AB42370D for ; Fri, 8 Jan 2021 01:30:36 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1729876AbhAHBaV (ORCPT ); Thu, 7 Jan 2021 20:30:21 -0500 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:47184 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1729855AbhAHBaU (ORCPT ); Thu, 7 Jan 2021 20:30:20 -0500 Received: from mail-qk1-x749.google.com (mail-qk1-x749.google.com [IPv6:2607:f8b0:4864:20::749]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 66124C0612A0 for ; Thu, 7 Jan 2021 17:29:07 -0800 (PST) Received: by mail-qk1-x749.google.com with SMTP id e25so7918821qka.3 for ; Thu, 07 Jan 2021 17:29:07 -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=ZHuHq1gX+rq+gSbDq4B8XNZLvR61GpcraAJJ94pG5jI=; b=n3wOhNlwvyXw4HZZk7N77vwCHd/iR01CfCyBgoB0P4g5WYyP9L4b/JLXPZX6lUKD+C LVQeyta6aZyaSpnIA1WLGCK60IK9lm6I9BwRlKijkskFOcLqLkxfjYw4iQJkrYHRKEfB wIg0N6KnqF95/looJaAv6BGrD8C0RxqhISgjozlHJzjZaLzW7tpxULLbKAQiyQ/BADAA GtOj1cRzgOILZnCqWiyGwiHVTY1VE0gp/XqlI6emnrhOnC4POLIGcjvArNe0i6Xmd38Z WcHMfyoeiQEg3eoQCIauLC5Zgt1Brrdni9kIXFsvnSfbNhcvYDuIsKglZyGoMideN5/4 9faA== 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=ZHuHq1gX+rq+gSbDq4B8XNZLvR61GpcraAJJ94pG5jI=; b=B/W3JTDdvh7kLobPFV7rMSrqJO7egKpD5ItVu28UwUNCMHDbdYQ6nVvEXtRVn/v31y jLdttaAgfjcTSj3MHW0sw15VOSHS/sDQ6ehgdIpKHHUd9/ymsB5cuynYwwhTBhAp/OoU KYnRxBfs8nZZXNeXud/3gW7DthGdVqKCz24VpOkWjesH5zbEdzOc4lbv52dDKs8h5YAH x3OvN9Q23UDBn8y60Tt0eT4ehNJa7xhvUwqFQHlgYn+cO5mhPCw1SkceSbqwxc2BIBCR uCH/1U5DnruISC1IcT24m/J1+E/Vf+6lpaGkSWWPyZwiF0xE6XIjNn93vSwlBu5eHK/Y /qnQ== X-Gm-Message-State: AOAM53051J4ZzMAWUD/JheE//lkxYJRG+NJNeDw7uPuz1txNKMTpOMfM 7+C55XuTrQ+YGSGg82fDlfx47ZIW66JF X-Google-Smtp-Source: ABdhPJxtCr1FuLGd3jUgdrALOLHJ3pQLuqVJ8xwNqCOs0HZRNRe/Kj6a1CL5fBPQ4THyxzd2Di1MC3ME9aMm 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:ad4:4f11:: with SMTP id fb17mr1429085qvb.46.1610069346396; Thu, 07 Jan 2021 17:29:06 -0800 (PST) Date: Thu, 7 Jan 2021 17:28:46 -0800 In-Reply-To: <20210108012846.4134815-1-vipinsh@google.com> Message-Id: <20210108012846.4134815-3-vipinsh@google.com> Mime-Version: 1.0 References: <20210108012846.4134815-1-vipinsh@google.com> X-Mailer: git-send-email 2.29.2.729.g45daf8777d-goog Subject: [Patch v4 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 63521cd36ce5..b6ea47b9e882 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.729.g45daf8777d-goog