morgan/systemd
1
0
Fork 0
mirror of https://github.com/morgan9e/systemd synced 2026-04-14 00:14:32 +09:00
Code Issues Packages Projects Releases Wiki Activity

docs/package-notes: extend description to support PE/COFF files

Browse Source 
The package notes are nice standard mechanism to figure out the exact name and
version of a program or a library stored in a file, without running the code.
In the beginning this was designed for the purpose of analyzing core dumps, but
we've since started to use it more generically to identify files. The same need
to identify PE/COFF files occurs, for example for systemd-boot and other files
intended for UEFI. It has also been requested by people working on bootupd
(https://github.com/coreos/bootupd).

The text is changed to say "Executable" or "ELF or PE/COFF" wherever "ELF" was
used previously.

The description for PE/COFF files is very brief. AFAIK, we don't have the same
"note" mechanism there [1], so just a normal section is used. The alignment
rules for PE/UEFI are different and change over time, so no specific alignment
is specified.

Other requirements for the PE/COFF section are based on what ukify currently
does for the .osrel section:
  5 .osrel        00000056  000000010132f000  000000010132f000  0002b600  2**2
                  CONTENTS, ALLOC, LOAD, READONLY, DATA

The name ".pkgnote" is used as suggested by Daan De Meyer. This corresponds to
the ".note.package" name used for ELF. ".package" was also suggested, but I
think that is too generic and carries more risk of a conflict with a different
use.

[1] https://learn.microsoft.com/en-us/windows/win32/debug/pe-format

Also zero/0 is replaced by NUL to clarify that a single 0 byte is meant.
This commit is contained in:
Zbigniew Jędrzejewski-Szmek
2024-12-19 12:15:59 +01:00
parent 0ab04876f2
commit bafe34ddbe
1 changed files with 35 additions and 14 deletions
Download Patch File Download Diff File Expand all files Collapse all files

49
docs/PACKAGE_METADATA_FOR_EXECUTABLE_FILES.md
View File

@@ -1,14 +1,15 @@
---
title: Package Metadata for ELF Files
title: Package Metadata for Executable Files
category: Interfaces
layout: default
SPDX-License-Identifier: LGPL-2.1-or-later
---
# Package Metadata for Core Files
# Package Metadata for Executable Files
*Intended audience: hackers working on userspace subsystems that create ELF binaries
or parse ELF core files.*
*Intended audience: hackers working on userspace subsystems that
create or manipulate ELF or PE/COFF binaries
or parse core files.*
## Motivation
@@ -41,24 +42,44 @@ This document will attempt to define a common metadata format specification, so
multiple implementers might use it when building packages, or core file analyzers, and
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, 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.
Implementers working on parsing the metadata should not assume a specific list of names,
but parse anything that is included in the JSON object.
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.
* Section header
### ELF header section
The metadata will be embedded in a single, 4 byte-aligned, allocated, NUL-padded,
read-only ELF header section, in a name-value JSON object format.
The JSON string is terminated with a NUL
and subsequently padded with NULs to a multiple of four bytes.
The `note type` must be set during creation and checked when reading.
Section: `.note.package`<br/>
`note type`: `0xcafe1a7e`<br/>
Owner: `FDO` (FreeDesktop.org)<br/>
Value: a single JSON object encoded as a zero-terminated UTF-8 string
Value: a single JSON object encoded as a NUL-terminated UTF-8 string
* JSON payload
### PE/COFF section
The metadata will be embedded in a single, allocated, NUL-padded,
read-only COFF data section,
in a name-value JSON object format.
The JSON string is terminated with a NUL
and subsequently padded with NULs if appropriate.
The `IMAGE_SCN_CNT_INITIALIZED_DATA` section flag shall be set.
The alignment and padding shall be chosen as appropriate for the use of the PE/COFF file.
Section: `.pkgnote`<br/>
Value: a single JSON object encoded as a NUL-terminated UTF-8 string
### JSON payload
```json
{
@@ -74,7 +95,7 @@ Value: a single JSON object encoded as a zero-terminated UTF-8 string
```
The format is a single JSON object,
encoded as a zero-terminated `UTF-8` string.
encoded as a NUL-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 characters or use `\uXXX` escaping.