From bedd92b956f42403e1dbc400ccda8f18efee9e68 Mon Sep 17 00:00:00 2001 From: Luca Boccassi Date: Tue, 30 Nov 2021 12:36:16 +0000 Subject: [PATCH 1/2] docs: clarify JSON terms in COREDUMP_PACKAGE_METADATA --- docs/COREDUMP_PACKAGE_METADATA.md | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) diff --git a/docs/COREDUMP_PACKAGE_METADATA.md b/docs/COREDUMP_PACKAGE_METADATA.md index 705d5d695a..461cb600c5 100644 --- a/docs/COREDUMP_PACKAGE_METADATA.md +++ b/docs/COREDUMP_PACKAGE_METADATA.md @@ -34,9 +34,9 @@ multiple implementers might use it when building packages, or core file analyzer so on. The metadata will be embedded in a single, new, 4-bytes-aligned, allocated, 0-padded, -read-only ELF header section, in a key-value JSON format. Implementers working on parsing -core files should not assume a specific list of keys, but parse anything that is included -in the section. Implementers working on build tools should strive to use the same key +read-only ELF header section, in a name-value JSON object format. Implementers working on parsing +core files should not assume a specific list of names, but parse anything that is included +in the section. Implementers working on build tools should strive to use the same names, for consistency. The most common will be listed here. When corresponding to the content of os-release, the values should match, again for consistency. @@ -49,7 +49,7 @@ the original executable, debuginfo and sources, to further facilitate debugging. SECTION: `.note.package` node-id: `0xcafe1a7e` Owner: `FDO` (FreeDesktop.org) -Value: a JSON string with the structure described below +Value: a single JSON object encoded as a zero-terminated UTF-8 string ``` * JSON payload @@ -67,6 +67,11 @@ Value: a JSON string with the structure described below } ``` +The format is a single JSON object, encoded as a zero-terminated `UTF-8` string. +Each name in the object shall be unique as per recommendations of +[RFC8259](https://datatracker.ietf.org/doc/html/rfc8259#section-4). Strings shall +not contain any control character, nor use `\uXXX` escaping. + When it comes to JSON numbers, this specification assumes that JSON parsers processing this information are capable of reproducing the full signed 53bit integer range (i.e. -2⁵³+1…+2⁵³-1) as well as the full 64bit IEEE floating From 45f822ceb31e4034d66ad1dd05462f906e166828 Mon Sep 17 00:00:00 2001 From: Luca Boccassi Date: Tue, 30 Nov 2021 14:42:43 +0000 Subject: [PATCH 2/2] docs: clarify ELF note usage in COREDUMP_PACKAGE_METADATA --- docs/COREDUMP_PACKAGE_METADATA.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/COREDUMP_PACKAGE_METADATA.md b/docs/COREDUMP_PACKAGE_METADATA.md index 461cb600c5..db75ad1432 100644 --- a/docs/COREDUMP_PACKAGE_METADATA.md +++ b/docs/COREDUMP_PACKAGE_METADATA.md @@ -36,9 +36,9 @@ so on. The metadata will be embedded in a single, new, 4-bytes-aligned, allocated, 0-padded, read-only ELF header section, in a name-value JSON object format. Implementers working on parsing core files should not assume a specific list of names, but parse anything that is included -in the section. Implementers working on build tools should strive to use the same -names, for consistency. The most common will be listed here. When corresponding to the -content of os-release, the values should match, again for consistency. +in the section, and should look for the note using the `note type`. Implementers working on +build tools should strive to use the same names, for consistency. The most common will be +listed here. When corresponding to the content of os-release, the values should match, again for consistency. If available, the metadata should also include the debuginfod server URL that can provide the original executable, debuginfo and sources, to further facilitate debugging. @@ -47,7 +47,7 @@ the original executable, debuginfo and sources, to further facilitate debugging. ``` SECTION: `.note.package` -node-id: `0xcafe1a7e` +note type: `0xcafe1a7e` Owner: `FDO` (FreeDesktop.org) Value: a single JSON object encoded as a zero-terminated UTF-8 string ```