[PATCH] kbuild: doc: describe the error caused by pre-epoch timestamp

[PATCH] kbuild: doc: describe the error caused by pre-epoch timestamp

[Gang Yan]

From: Gang Yan <yangang@kylinos.cn>

This patch documents the compilation error that occurs with a pre-epoch
KBUILD_BUILD_TIMESTAMP. By providing an example command and the resulting
error, it helps users identify and avoid this issue.

Suggested-by: David Disseldorp <ddiss@suse.de>
Signed-off-by: Gang Yan <yangang@kylinos.cn>
---
 Documentation/kbuild/kbuild.rst | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/Documentation/kbuild/kbuild.rst b/Documentation/kbuild/kbuild.rst
index 3388a10f2dcc..1ffc782d2061 100644
--- a/Documentation/kbuild/kbuild.rst
+++ b/Documentation/kbuild/kbuild.rst
@@ -331,6 +331,15 @@ UTS_VERSION definition (uname -v in the running kernel). The value has to
 be a string that can be passed to date -d. The default value
 is the output of the date command at one point during build.
 
+However, when the date command retrieves a timestamp that falls into
+pre-epoch times (i.e., dates before the Unix epoch, January 1, 1970),
+the kernel will raise an error during the compilation of initramfs. E.g.::
+
+    $ KBUILD_BUILD_TIMESTAMP="Sat Jan 1 00:00:00 UTC 0000" make
+    ...
+    ERROR: Timestamp out of range for cpio format'
+    ...
+
 KBUILD_BUILD_USER, KBUILD_BUILD_HOST
 ------------------------------------
 These two variables allow to override the user@host string displayed during
-- 
2.43.0

Re: [PATCH] kbuild: doc: describe the error caused by pre-epoch timestamp

[David Disseldorp]

On Thu, 16 Oct 2025 14:08:55 +0800, Gang Yan wrote:

> From: Gang Yan <yangang@kylinos.cn>
> 
> This patch documents the compilation error that occurs with a pre-epoch
> KBUILD_BUILD_TIMESTAMP. By providing an example command and the resulting
> error, it helps users identify and avoid this issue.

Adding the example is helpful, but my preference would to use a valid
one (which can be copied).

> Suggested-by: David Disseldorp <ddiss@suse.de>
> Signed-off-by: Gang Yan <yangang@kylinos.cn>
> ---
>  Documentation/kbuild/kbuild.rst | 9 +++++++++
>  1 file changed, 9 insertions(+)
> 
> diff --git a/Documentation/kbuild/kbuild.rst b/Documentation/kbuild/kbuild.rst
> index 3388a10f2dcc..1ffc782d2061 100644
> --- a/Documentation/kbuild/kbuild.rst
> +++ b/Documentation/kbuild/kbuild.rst
> @@ -331,6 +331,15 @@ UTS_VERSION definition (uname -v in the running kernel). The value has to
>  be a string that can be passed to date -d. E.g.:

   <valid example here>

> The default value
>  is the output of the date command at one point during build.
>  
> +However, when the date command retrieves a timestamp that falls into
> +pre-epoch times (i.e., dates before the Unix epoch, January 1, 1970),
> +the kernel will raise an error during the compilation of initramfs. E.g.::

This assumes CONFIG_BLK_DEV_INITRD=y, and doesn't cover why initramfs
uses the date in the first place. How about reworking it to something
like the following:

  If provided, this timestamp will also be used for mtime fields within
  any initramfs archive. Initramfs mtimes are 32-bit, so dates before
  the 1970 Unix epoch, or after 2106-02-07 06:28:15 UTC will fail.

With that, feel free to add:
Reviewed-by: David Disseldorp <ddiss@suse.de>

Thanks, David