linux-kernel - Re: [PATCH] x86/Documentation: explain LINUX_EFI_INITRD_MEDIA

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [day] [month] [year] [list]

Message-ID: <cfeacf42-c489-4b84-a21a-3cd126759cfc@infradead.org>
Date: Thu, 11 Sep 2025 14:22:32 -0700
From: Randy Dunlap <rdunlap@...radead.org>
To: Hugo Osvaldo Barrera <hugo@...nothugo.nl>,
 Bagas Sanjaya <bagasdotme@...il.com>, Ard Biesheuvel <ardb@...nel.org>
Cc: Linux Kernel Mailing List <linux-kernel@...r.kernel.org>,
 Linux Documentation <linux-doc@...r.kernel.org>,
 Linux EFI <linux-efi@...r.kernel.org>, Jonathan Corbet <corbet@....net>,
 Thomas Gleixner <tglx@...utronix.de>, Ingo Molnar <mingo@...hat.com>,
 Borislav Petkov <bp@...en8.de>, Dave Hansen <dave.hansen@...ux.intel.com>,
 x86@...nel.org, "H. Peter Anvin" <hpa@...or.com>
Subject: Re: [PATCH] x86/Documentation: explain LINUX_EFI_INITRD_MEDIA_GUID

Hi,

On 9/11/25 5:16 AM, Hugo Osvaldo Barrera wrote:
> 
> 
> On Thu, 11 Sep 2025, at 13:50, Bagas Sanjaya wrote:
>> On Thu, Sep 11, 2025 at 01:22:54PM +0200, Hugo Osvaldo Barrera wrote:
>>> On Thu, 11 Sep 2025, at 08:46, Ard Biesheuvel wrote:
>>>> On Wed, 10 Sept 2025 at 03:58, Bagas Sanjaya <bagasdotme@...il.com> wrote:
>>>>> +.. _pe-coff-entry-point:
>>>>> +
>>>>> +PE/COFF entry point
>>>>> +===================
>>>>> +
>>>>> +When compiled with ``CONFIG_EFI_STUB=y``, the kernel can be executed as a
>>>>> +regular PE/COFF binary. See Documentation/admin-guide/efi-stub.rst for
>>>>> +implementation details.
>>>>> +
>>>
>>> This should be a link rather than a path to the source file.
>>
>> I think you miss the point of Jon's comment on your original submission [1].
>> Long story short, in Sphinx, one would cross-reference to other documentation
>> files (so-called internal linking) either with :doc: or :ref: directives. In
>> case of kernel docs, there is third and preferred way: simply mentioning the
>> full docs path. The latter is preferred as it is simpler and also allows
>> building only portion of docs (with make SPHINXDIRS=<dir>) without triggering
>> any reference warnings. Hence why I did addressing his comment.
>> For more information, see Documentation/doc-guide/sphinx.rst.
>>
> 
> The RST files are source files to produce documentation in HTML and PDF. If you
> write the path to another source file, the resulting HTML files don't have
> any link and the reference is completely lost.
> 
> Given the path Documentation/admin-guide/efi-stub.rst, if I'm looking at
> https://www.kernel.org/doc/html/latest/arch/x86/boot.html, I'd have on idea
> where this path is pointing me to.

I applied the original patch from Bagas. I'm looking at
arch/x86/boot.html. It shows me:

1.16. PE/COFF entry point

  When compiled with CONFIG_EFI_STUB=y, the kernel can be executed as a regular PE/COFF binary. See The EFI Boot Stub for implementation details.

where "The EFI Boot Stub" is (in my browser) in blue and underlined and is a link to
admin-guide/efi-stub.html

Is this what you are saying will not happen or am I
completely confused?  Kernel documentation automarkup handles
Documentation/.../*.rst file links automatically.

> WRT Jon's comment on the original submission, I do agree that the label
> is unnecessary, since we can link to the page directly without a label at
> the top.

Thanks.
-- 
~Randy