From 759f58ad646648abeaef435f161a73d7202f793b Mon Sep 17 00:00:00 2001
From: Odin Ugedal <odin@ugedal.com>
Date: Sun, 9 Jun 2019 08:24:27 +0200
Subject: [PATCH] config-linux: add more info about hugetlb page size

Currently the docs don't say anything about what the "pageSize" is other
than the fact that it is a string. This makes it easier for developers
to understand how it works, and may help avoiding mistakes which are
hard to spot.

Signed-off-by: Odin Ugedal <odin@ugedal.com>
---
 config-linux.md                            |  7 +++++++
 config.md                                  |  4 ++++
 schema/config-linux.json                   |  3 ++-
 schema/test/config/bad/linux-hugepage.json | 16 ++++++++++++++++
 schema/test/config/good/spec-example.json  |  4 ++++
 specs-go/config.go                         |  1 +
 6 files changed, 34 insertions(+), 1 deletion(-)
 create mode 100644 schema/test/config/bad/linux-hugepage.json

diff --git a/config-linux.md b/config-linux.md
index 4e64ad5d1..a2d1f4e5f 100644
--- a/config-linux.md
+++ b/config-linux.md
@@ -394,6 +394,9 @@ For more information, see the kernel cgroups documentation about [HugeTLB][cgrou
 Each entry has the following structure:
 
 * **`pageSize`** *(string, REQUIRED)* - hugepage size
+    The value has the format "<size><unit-prefix>B" (64KB, 2MB, 1GB), and must match the <hugepagesize> of the
+    corresponding control file found in "/sys/fs/cgroup/hugetlb/hugetlb.<hugepagesize>.limit_in_bytes".
+    Values of <unit-prefix> are intended to be parsed using base 1024 ("1KB" = 1024, "1MB" = 1048576, etc).
 * **`limit`** *(uint64, REQUIRED)* - limit in bytes of *hugepagesize* HugeTLB usage
 
 #### Example
@@ -403,6 +406,10 @@ Each entry has the following structure:
         {
             "pageSize": "2MB",
             "limit": 209715200
+        },
+        {
+            "pageSize": "64KB",
+            "limit": 1000000
         }
    ]
 ```
diff --git a/config.md b/config.md
index 357f319dd..ea281ce66 100644
--- a/config.md
+++ b/config.md
@@ -710,6 +710,10 @@ Here is a full example `config.json` for reference.
                 {
                     "pageSize": "2MB",
                     "limit": 9223372036854772000
+                },
+                {
+                    "pageSize": "64KB",
+                    "limit": 1000000
                 }
             ],
             "memory": {
diff --git a/schema/config-linux.json b/schema/config-linux.json
index f9cc35b13..5aa03c423 100644
--- a/schema/config-linux.json
+++ b/schema/config-linux.json
@@ -124,7 +124,8 @@
                             "type": "object",
                             "properties": {
                                 "pageSize": {
-                                    "type": "string"
+                                    "type": "string",
+                                    "pattern": "^[1-9][0-9]*[KMG]B$"
                                 },
                                 "limit": {
                                     "$ref": "defs.json#/definitions/uint64"
diff --git a/schema/test/config/bad/linux-hugepage.json b/schema/test/config/bad/linux-hugepage.json
new file mode 100644
index 000000000..aea35eb7a
--- /dev/null
+++ b/schema/test/config/bad/linux-hugepage.json
@@ -0,0 +1,16 @@
+{
+    "ociVersion": "1.0.0",
+    "root": {
+        "path": "rootfs"
+    },
+    "linux": {
+        "resources": {
+            "hugepageLimits": [
+                {
+                    "limit": 1234123,
+                    "pageSize": "64kB"
+                }
+            ]
+        }
+    }
+}
diff --git a/schema/test/config/good/spec-example.json b/schema/test/config/good/spec-example.json
index c1390c379..67815349d 100644
--- a/schema/test/config/good/spec-example.json
+++ b/schema/test/config/good/spec-example.json
@@ -232,6 +232,10 @@
                 {
                     "pageSize": "2MB",
                     "limit": 9223372036854772000
+                },
+                {
+                    "pageSize": "64KB",
+                    "limit": 1000000
                 }
             ],
             "oomScoreAdj": 100,
diff --git a/specs-go/config.go b/specs-go/config.go
index c36010cc0..48e621c99 100644
--- a/specs-go/config.go
+++ b/specs-go/config.go
@@ -219,6 +219,7 @@ type POSIXRlimit struct {
 // LinuxHugepageLimit structure corresponds to limiting kernel hugepages
 type LinuxHugepageLimit struct {
 	// Pagesize is the hugepage size
+	// Format: "<size><unit-prefix>B' (e.g. 64KB, 2MB, 1GB, etc.)
 	Pagesize string `json:"pageSize"`
 	// Limit is the limit of "hugepagesize" hugetlb usage
 	Limit uint64 `json:"limit"`