[PATCH] Documentation: Fix incorrect paths/magic in magic numbers rst

[PATCH] Documentation: Fix incorrect paths/magic in magic numbers rst

[Nir Lichtman]

Fix some no longer true header/c file paths and correct the BAYCOM_MAGIC
value to be decimal as in the source instead of incorrectly hexadecimal

Signed-off-by: Nir Lichtman <nir@lichtman.org>
---
 Documentation/staging/magic-number.rst | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/Documentation/staging/magic-number.rst b/Documentation/staging/magic-number.rst
index 7029c3c084ee..79afddf0e692 100644
--- a/Documentation/staging/magic-number.rst
+++ b/Documentation/staging/magic-number.rst
@@ -68,11 +68,11 @@ Changelog::
 ===================== ================ ======================== ==========================================
 Magic Name            Number           Structure                File
 ===================== ================ ======================== ==========================================
-PG_MAGIC              'P'              pg_{read,write}_hdr      ``include/linux/pg.h``
+PG_MAGIC              'P'              pg_{read,write}_hdr      ``include/uapi/linux/pg.h``
 APM_BIOS_MAGIC        0x4101           apm_user                 ``arch/x86/kernel/apm_32.c``
 FASYNC_MAGIC          0x4601           fasync_struct            ``include/linux/fs.h``
-SLIP_MAGIC            0x5302           slip                     ``drivers/net/slip.h``
-BAYCOM_MAGIC          0x19730510       baycom_state             ``drivers/net/baycom_epp.c``
+SLIP_MAGIC            0x5302           slip                     ``drivers/net/slip/slip.h``
+BAYCOM_MAGIC          19730510         baycom_state             ``drivers/net/hamradio/baycom_epp.c``
 HDLCDRV_MAGIC         0x5ac6e778       hdlcdrv_state            ``include/linux/hdlcdrv.h``
 KV_MAGIC              0x5f4b565f       kernel_vars_s            ``arch/mips/include/asm/sn/klkernvars.h``
 CODA_MAGIC            0xC0DAC0DA       coda_file_info           ``fs/coda/coda_fs_i.h``
-- 
2.39.2

Re: [PATCH] Documentation: Fix incorrect paths/magic in magic numbers rst

[Jonathan Corbet]

Nir Lichtman <nir@lichtman.org> writes:

> Fix some no longer true header/c file paths and correct the BAYCOM_MAGIC
> value to be decimal as in the source instead of incorrectly hexadecimal
>
> Signed-off-by: Nir Lichtman <nir@lichtman.org>
> ---
>  Documentation/staging/magic-number.rst | 6 +++---
>  1 file changed, 3 insertions(+), 3 deletions(-)

I've applied this, thanks.  I do continue to wonder about the value of
this file in general, though...

jon

Re: [PATCH] Documentation: Fix incorrect paths/magic in magic numbers rst

[Nir Lichtman]

On Mon, Nov 04, 2024 at 12:35:30PM -0700, Jonathan Corbet wrote:
> Nir Lichtman <nir@lichtman.org> writes:
> 
> > Fix some no longer true header/c file paths and correct the BAYCOM_MAGIC
> > value to be decimal as in the source instead of incorrectly hexadecimal
> >
> > Signed-off-by: Nir Lichtman <nir@lichtman.org>
> > ---
> >  Documentation/staging/magic-number.rst | 6 +++---
> >  1 file changed, 3 insertions(+), 3 deletions(-)
> 
> I've applied this, thanks.  I do continue to wonder about the value of
> this file in general, though...

Agreed, it feels pretty much like abandoned book keeping that gives minimal
value since the chance of magics colliding is slim, but I think the general tip
before the table of magics is pretty good.

What is your opinion about integrating the tip in a different page and deleting
this page entirely?

Thanks,
Nir

> 
> jon

Re: [PATCH] Documentation: Fix incorrect paths/magic in magic numbers rst

[Jonathan Corbet]

Nir Lichtman <nir@lichtman.org> writes:

> On Mon, Nov 04, 2024 at 12:35:30PM -0700, Jonathan Corbet wrote:
>> Nir Lichtman <nir@lichtman.org> writes:
>> 
>> > Fix some no longer true header/c file paths and correct the BAYCOM_MAGIC
>> > value to be decimal as in the source instead of incorrectly hexadecimal
>> >
>> > Signed-off-by: Nir Lichtman <nir@lichtman.org>
>> > ---
>> >  Documentation/staging/magic-number.rst | 6 +++---
>> >  1 file changed, 3 insertions(+), 3 deletions(-)
>> 
>> I've applied this, thanks.  I do continue to wonder about the value of
>> this file in general, though...
>
> Agreed, it feels pretty much like abandoned book keeping that gives minimal
> value since the chance of magics colliding is slim, but I think the general tip
> before the table of magics is pretty good.
>
> What is your opinion about integrating the tip in a different page and deleting
> this page entirely?

Well, that's part of my reasoning, actually.  I assume you're talking
about this:

> It is a **very** good idea to protect kernel data structures with magic
> numbers.  This allows you to check at run time whether (a) a structure
> has been clobbered, or (b) you've passed the wrong structure to a
> routine. 

The thing is, that's really not a guideline that anybody has followed
for many years.  I dug into this a while back:

  https://lwn.net/Articles/915163/

There was a series to remove all of this cruft a couple of years ago
that the author eventually gave up on:

  https://lore.kernel.org/lkml/cover.1668128257.git.nabijaczleweli@nabijaczleweli.xyz/

Honestly, I think the best thing to do is to simply remove the file.

Thanks,

jon

Re: [PATCH] Documentation: Fix incorrect paths/magic in magic numbers rst

[Nir Lichtman]

On Mon, Nov 04, 2024 at 01:10:56PM -0700, Jonathan Corbet wrote:
> Nir Lichtman <nir@lichtman.org> writes:
> >
> > Agreed, it feels pretty much like abandoned book keeping that gives minimal
> > value since the chance of magics colliding is slim, but I think the general tip
> > before the table of magics is pretty good.
> >
> > What is your opinion about integrating the tip in a different page and deleting
> > this page entirely?
> 
> Well, that's part of my reasoning, actually.  I assume you're talking
> about this:
> 
> > It is a **very** good idea to protect kernel data structures with magic
> > numbers.  This allows you to check at run time whether (a) a structure
> > has been clobbered, or (b) you've passed the wrong structure to a
> > routine. 
> 
> The thing is, that's really not a guideline that anybody has followed
> for many years.  I dug into this a while back:
> 
>   https://lwn.net/Articles/915163/

Nice, interesting article and history

> 
> There was a series to remove all of this cruft a couple of years ago
> that the author eventually gave up on:
> 
>   https://lore.kernel.org/lkml/cover.1668128257.git.nabijaczleweli@nabijaczleweli.xyz/
> 
> Honestly, I think the best thing to do is to simply remove the file.

Agreed, looks like he got some pushback from removing the magics from
the source itself, but I don't think that should stop from removing this doc

Thanks,
Nir