[PATCH] docs/sp_SP: Add process magic-number translation

[PATCH] docs/sp_SP: Add process magic-number translation

[Carlos Bilbao]

Translate the following document into Spanish:

- process/magic-number.rst

Signed-off-by: Carlos Bilbao <carlos.bilbao@amd.com>
---
 .../translations/sp_SP/process/index.rst      |  1 +
 .../sp_SP/process/magic-number.rst            | 90 +++++++++++++++++++
 2 files changed, 91 insertions(+)
 create mode 100644 Documentation/translations/sp_SP/process/magic-number.rst

diff --git a/Documentation/translations/sp_SP/process/index.rst b/Documentation/translations/sp_SP/process/index.rst
index ca95cd296ee1..c978a8132ce1 100644
--- a/Documentation/translations/sp_SP/process/index.rst
+++ b/Documentation/translations/sp_SP/process/index.rst
@@ -16,3 +16,4 @@
    code-of-conduct
    kernel-enforcement-statement
    email-clients
+   magic-number
diff --git a/Documentation/translations/sp_SP/process/magic-number.rst b/Documentation/translations/sp_SP/process/magic-number.rst
new file mode 100644
index 000000000000..6459f130f1e2
--- /dev/null
+++ b/Documentation/translations/sp_SP/process/magic-number.rst
@@ -0,0 +1,90 @@
+.. include:: ../disclaimer-sp.rst
+
+:Original: :ref:`Documentation/process/magic-number.rst <magicnumbers>`
+:Translator: Carlos Bilbao <carlos.bilbao@amd.com>
+
+.. _sp_magicnumbers:
+
+Números mágicos de Linux
+========================
+
+Este archivo es un registro de los números mágicos que están en uso. Cuando
+usted incluya un número mágico a una estructura, también debe agregarlo a
+este documento, ya que es mejor si los números mágicos utilizados por
+varias estructuras son únicos.
+
+Es una muy buena idea proteger las estructuras de datos del kernel con
+números mágicos. Esto le permite verificar en tiempo de ejecución si (a)
+una estructura ha sido manipulada, o (b) ha pasado la estructura incorrecta
+a una rutina. Esto último es especialmente útil --- particularmente cuando
+pasa punteros a estructuras a través de un puntero void *. El código tty,
+por ejemplo, hace esto con frecuencia para pasar información específica del
+driver y líneas de estructuras específicas de protocolo de un lado al
+otro.
+
+La forma de usar números mágicos es declararlos al principio de la
+estructura, así::
+
+	struct tty_ldisc {
+		int	magic;
+		...
+	};
+
+Por favor, siga este método cuando agregue futuras mejoras al kernel! Me ha
+ahorrado innumerables horas de depuración, especialmente en los casos
+complicados donde una matriz ha sido invadida y las estructuras que siguen
+a la matriz se han sobrescrito. Usando este método, estos casos se detectan
+de forma rápida y segura.
+
+Changelog::
+
+					Theodore Ts'o
+					31 Mar 94
+
+  La tabla mágica ha sido actualizada para Linux 2.1.55.
+
+					Michael Chastain
+					<mailto:mec@shout.net>
+					22 Sep 1997
+
+  Ahora debería estar actualizada con Linux 2.1.112. Porque
+  estamos en fase de "feature freeze", es muy poco probable que
+  algo cambiará antes de 2.2.x. Las entradas son
+  ordenados por campo numérico.
+
+					Krzysztof G. Baranowski
+					<mailto: kgb@knm.org.pl>
+					29 Jul 1998
+
+  Se actualizó la tabla mágica a Linux 2.5.45. Justo sobre el feature
+  freeze, pero es posible que algunos nuevos números mágicos se cuelen en
+  el kernel antes de 2.6.x todavía.
+
+					Petr Baudis
+					<pasky@ucw.cz>
+					03 Nov 2002
+
+  La tabla mágica ha sido actualizada para Linux 2.5.74.
+
+					Fabian Frederick
+					<ffrederick@users.sourceforge.net>
+					09 Jul 2003
+
+===================== ================ ======================== ==========================================
+Magic Name            Number           Structure                File
+===================== ================ ======================== ==========================================
+PG_MAGIC              'P'              pg_{read,write}_hdr      ``include/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``
+MGSLPC_MAGIC          0x5402           mgslpc_info              ``drivers/char/pcmcia/synclink_cs.c``
+BAYCOM_MAGIC          0x19730510       baycom_state             ``drivers/net/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``
+YAM_MAGIC             0xF10A7654       yam_port                 ``drivers/net/hamradio/yam.c``
+CCB_MAGIC             0xf2691ad2       ccb                      ``drivers/scsi/ncr53c8xx.c``
+QUEUE_MAGIC_FREE      0xf7e1c9a3       queue_entry              ``drivers/scsi/arm/queue.c``
+QUEUE_MAGIC_USED      0xf7e1cc33       queue_entry              ``drivers/scsi/arm/queue.c``
+NMI_MAGIC             0x48414d4d455201 nmi_s                    ``arch/mips/include/asm/sn/nmi.h``
+===================== ================ ======================== ==========================================
-- 
2.34.1

Re: [PATCH] docs/sp_SP: Add process magic-number translation

[Jonathan Corbet]

Carlos Bilbao <carlos.bilbao@amd.com> writes:

> Translate the following document into Spanish:
>
> - process/magic-number.rst
>
> Signed-off-by: Carlos Bilbao <carlos.bilbao@amd.com>
> ---
>  .../translations/sp_SP/process/index.rst      |  1 +
>  .../sp_SP/process/magic-number.rst            | 90 +++++++++++++++++++
>  2 files changed, 91 insertions(+)
>  create mode 100644 Documentation/translations/sp_SP/process/magic-number.rst

There was a series out there to delete this file entirely:

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

I wonder whatever became of that?

Thanks,

jon

Re: [PATCH] docs/sp_SP: Add process magic-number translation

[Ahelenia Ziemiańska]

[-- Attachment #1: Type: text/plain, Size: 360 bytes --]

On Wed, Jan 25, 2023 at 12:39:26PM -0700, Jonathan Corbet wrote:
> There was a series out there to delete this file entirely:
>   https://lore.kernel.org/lkml/cover.1668128257.git.nabijaczleweli@nabijaczleweli.xyz/
> I wonder whatever became of that?
No-one cared enough to apply and I got over re-sending it,
so only part of the whole clean-up landed.

Best,

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH] docs/sp_SP: Add process magic-number translation

[Jonathan Corbet]

Ahelenia Ziemiańska <nabijaczleweli@nabijaczleweli.xyz> writes:

> On Wed, Jan 25, 2023 at 12:39:26PM -0700, Jonathan Corbet wrote:
>> There was a series out there to delete this file entirely:
>>   https://lore.kernel.org/lkml/cover.1668128257.git.nabijaczleweli@nabijaczleweli.xyz/
>> I wonder whatever became of that?
> No-one cared enough to apply and I got over re-sending it,
> so only part of the whole clean-up landed.

That's too bad, I think it was a good cleanup.  Cross-subsystem changes
like this always take some work to get through.  If you were to persist,
I expect you'd eventually get there.

I'm tempted to do the magic-number.rst removal regardless, lest it tempt
others into trying to add more of them.

Thanks,

jon

Re: [PATCH] docs/sp_SP: Add process magic-number translation

[kernel test robot]

Hi Carlos,

I love your patch! Perhaps something to improve:

[auto build test WARNING on lwn/docs-next]
[also build test WARNING on next-20230127]
[cannot apply to linus/master v6.2-rc5]
[If your patch is applied to the wrong git tree, kindly drop us a note.
And when submitting patch, we suggest to use '--base' as documented in
https://git-scm.com/docs/git-format-patch#_base_tree_information]

url:    https://github.com/intel-lab-lkp/linux/commits/Carlos-Bilbao/docs-sp_SP-Add-process-magic-number-translation/20230128-103013
base:   git://git.lwn.net/linux.git docs-next
patch link:    https://lore.kernel.org/r/20230125181840.3007341-1-carlos.bilbao%40amd.com
patch subject: [PATCH] docs/sp_SP: Add process magic-number translation
reproduce:
        # https://github.com/intel-lab-lkp/linux/commit/386e4549b53d3e7f381ad80c954a1e783aedf1c6
        git remote add linux-review https://github.com/intel-lab-lkp/linux
        git fetch --no-tags linux-review Carlos-Bilbao/docs-sp_SP-Add-process-magic-number-translation/20230128-103013
        git checkout 386e4549b53d3e7f381ad80c954a1e783aedf1c6
        make menuconfig
        # enable CONFIG_COMPILE_TEST, CONFIG_WARN_MISSING_DOCUMENTS, CONFIG_WARN_ABI_ERRORS
        make htmldocs

If you fix the issue, kindly add following tag where applicable
| Reported-by: kernel test robot <lkp@intel.com>

All warnings (new ones prefixed by >>):

>> Documentation/translations/sp_SP/process/magic-number.rst:16: WARNING: Inline emphasis start-string without end-string.

vim +16 Documentation/translations/sp_SP/process/magic-number.rst

    15	
  > 16	Es una muy buena idea proteger las estructuras de datos del kernel con
    17	números mágicos. Esto le permite verificar en tiempo de ejecución si (a)
    18	una estructura ha sido manipulada, o (b) ha pasado la estructura incorrecta
    19	a una rutina. Esto último es especialmente útil --- particularmente cuando
    20	pasa punteros a estructuras a través de un puntero void *. El código tty,
    21	por ejemplo, hace esto con frecuencia para pasar información específica del
    22	driver y líneas de estructuras específicas de protocolo de un lado al
    23	otro.
    24	

-- 
0-DAY CI Kernel Test Service
https://github.com/intel/lkp-tests

Re: [PATCH] docs/sp_SP: Add process magic-number translation

[Jonathan Corbet]

Carlos Bilbao <carlos.bilbao@amd.com> writes:

> Translate the following document into Spanish:
>
> - process/magic-number.rst
>
> Signed-off-by: Carlos Bilbao <carlos.bilbao@amd.com>
> ---
>  .../translations/sp_SP/process/index.rst      |  1 +
>  .../sp_SP/process/magic-number.rst            | 90 +++++++++++++++++++
>  2 files changed, 91 insertions(+)
>  create mode 100644 Documentation/translations/sp_SP/process/magic-number.rst

I've gone ahead and applied this; if magic-number.rst goes, this one can
too :)

Thanks,

jon

Re: [PATCH] docs/sp_SP: Add process magic-number translation

[Jonathan Corbet]

Jonathan Corbet <corbet@lwn.net> writes:

> Carlos Bilbao <carlos.bilbao@amd.com> writes:
>
>> Translate the following document into Spanish:
>>
>> - process/magic-number.rst
>>
>> Signed-off-by: Carlos Bilbao <carlos.bilbao@amd.com>
>> ---
>>  .../translations/sp_SP/process/index.rst      |  1 +
>>  .../sp_SP/process/magic-number.rst            | 90 +++++++++++++++++++
>>  2 files changed, 91 insertions(+)
>>  create mode 100644 Documentation/translations/sp_SP/process/magic-number.rst
>
> I've gone ahead and applied this; if magic-number.rst goes, this one can
> too :)

...of course, the robot already pointed out this new warning:

  Documentation/translations/sp_SP/process/magic-number.rst:16: WARNING: Inline emphasis start-string without end-string.

I took the liberty of changing "void *" to "void \*" to make that go
away.

jon

Re: [PATCH] docs/sp_SP: Add process magic-number translation

[Carlos Bilbao]

On 1/31/23 15:46, Jonathan Corbet wrote:

> Jonathan Corbet <corbet@lwn.net> writes:
>
>> Carlos Bilbao <carlos.bilbao@amd.com> writes:
>>
>>> Translate the following document into Spanish:
>>>
>>> - process/magic-number.rst
>>>
>>> Signed-off-by: Carlos Bilbao <carlos.bilbao@amd.com>
>>> ---
>>>   .../translations/sp_SP/process/index.rst      |  1 +
>>>   .../sp_SP/process/magic-number.rst            | 90 +++++++++++++++++++
>>>   2 files changed, 91 insertions(+)
>>>   create mode 100644 Documentation/translations/sp_SP/process/magic-number.rst
>> I've gone ahead and applied this; if magic-number.rst goes, this one can
>> too :)
> ...of course, the robot already pointed out this new warning:
>
>    Documentation/translations/sp_SP/process/magic-number.rst:16: WARNING: Inline emphasis start-string without end-string.
>
> I took the liberty of changing "void *" to "void \*" to make that go
> away.


Thanks for handling that, didn't catch that warning in my system.


>
> jon

Thanks,
Carlos