diff options
Diffstat (limited to 'Documentation/translations/sp_SP/process')
13 files changed, 4490 insertions, 0 deletions
diff --git a/Documentation/translations/sp_SP/process/adding-syscalls.rst b/Documentation/translations/sp_SP/process/adding-syscalls.rst new file mode 100644 index 000000000..f21504c61 --- /dev/null +++ b/Documentation/translations/sp_SP/process/adding-syscalls.rst @@ -0,0 +1,632 @@ +.. include:: ../disclaimer-sp.rst + +:Original: :ref:`Documentation/process/adding-syscalls.rst <addsyscalls>` +:Translator: Mauricio Fuentes <mauriciofb@gmail.com> + +.. _sp_addsyscalls: + +Agregando una Nueva Llamada del Sistema +======================================= + +Este documento describe qué involucra agregar una nueva llamada del sistema +al kernel Linux, más allá de la presentación y consejos normales en +:ref:`Documentation/process/submitting-patches.rst <submittingpatches>` que +también puede encontrar traducido a este idioma. + +Alternativas a Llamadas del Sistema +----------------------------------- + +La primera cosa a considerar cuando se agrega una llamada al sistema es si +alguna alternativa es adecuada en su lugar. Aunque las llamadas al sistema +son los puntos de interacción entre el userspace y el kernel más obvios y +tradicionales, existen otras posibilidades -- elija la que mejor se adecúe +a su interfaz. + + - Si se puede hacer que la operación se parezca a un objeto filesystem, + podría tener más sentido crear un nuevo sistema de ficheros o + dispositivo. Esto también hará más fácil encapsular la nueva + funcionalidad en un módulo del kernel en vez de requerir que sea + construido junto al kernel principal. + + - Si la nueva funcionalidad involucra operaciones donde el kernel + notifica al userspace que algo ha pasado, entonces retornar un nuevo + descriptor de archivo para el objeto relevante permite al userspace + usar ``poll``/``select``/``epoll`` para recibir esta notificación. + + - Sin embargo, operaciones que no mapean a operaciones similares a + :manpage:`read(2)`/:manpage:`write(2)` tienen que ser implementadas + como solicitudes :manpage:`ioctl(2)`, las cuales pueden llevar a un + API algo opaca. + + - Si sólo está exponiendo información del runtime, un nuevo nodo en sysfs + (mire ``Documentation/filesystems/sysfs.rst``) o el filesystem ``/proc`` + podría ser más adecuado. Sin embargo, acceder a estos mecanismos + requiere que el filesystem relevante esté montado, lo que podría no ser + siempre el caso (e.g. en un ambiente namespaced/sandboxed/chrooted). + Evite agregar cualquier API a debugfs, ya que no se considera una + interfaz (interface) de 'producción' para el userspace. + + - Si la operación es específica a un archivo o descriptor de archivo + específico, entonces la opción de comando adicional :manpage:`fcntl(2)` + podría ser más apropiada. Sin embargo, :manpage:`fcntl(2)` es una + llamada al sistema multiplexada que esconde mucha complejidad, así que + esta opción es mejor cuando la nueva funcion es analogamente cercana a + la funcionalidad existente :manpage:`fcntl(2)`, o la nueva funcionalidad + es muy simple (por ejemplo, definir/obtener un flag simple relacionado a + un descriptor de archivo). + + - Si la operación es específica a un proceso o tarea particular, entonces + un comando adicional :manpage:`prctl(2)` podría ser más apropiado. Tal + como con :manpage:`fcntl(2)`, esta llamada al sistema es un multiplexor + complicado así que está reservado para comandos análogamente cercanos + del existente ``prctl()`` u obtener/definir un flag simple relacionado a + un proceso. + +Diseñando el API: Planeando para extensiones +-------------------------------------------- + +Una nueva llamada del sistema forma parte del API del kernel, y tiene que +ser soportada indefinidamente. Como tal, es una muy buena idea discutir +explícitamente el interface en las listas de correo del kernel, y es +importante planear para futuras extensiones del interface. + +(La tabla syscall está poblada con ejemplos históricos donde esto no se +hizo, junto con los correspondientes seguimientos de los system calls -- +``eventfd``/``eventfd2``, ``dup2``/``dup3``, ``inotify_init``/``inotify_init1``, +``pipe``/``pipe2``, ``renameat``/``renameat2`` -- así que aprenda de la +historia del kernel y planee extensiones desde el inicio.) + +Para llamadas al sistema más simples que sólo toman un par de argumentos, +la forma preferida de permitir futuras extensiones es incluir un argumento +flag a la llamada al sistema. Para asegurarse que el userspace pueda usar +de forma segura estos flags entre versiones del kernel, revise si los flags +contienen cualquier flag desconocido, y rechace la llamada al sistema (con +``EINVAL``) si ocurre:: + + if (flags & ~(THING_FLAG1 | THINGFLAG2 | THING_FLAG3)) + return -EINVAL; + +(Si no hay valores de flags usados aún, revise que los argumentos del flag +sean cero.) + +Para llamadas al sistema más sofisticadas que involucran un gran número de +argumentos, es preferible encapsular la mayoría de los argumentos en una +estructura que sea pasada a través de un puntero. Tal estructura puede +hacer frente a futuras extensiones mediante la inclusión de un argumento de +tamaño en la estructura:: + + struct xyzzy_params { + u32 size; /* userspace define p->size = sizeof(struct xyzzy_params) */ + u32 param_1; + u64 param_2; + u64 param_3; + }; + +Siempre que cualquier campo añadido subsecuente, digamos ``param_4``, sea +diseñado de forma tal que un valor cero, devuelva el comportamiento previo, +entonces permite versiones no coincidentes en ambos sentidos: + + - Para hacer frente a programas del userspace más modernos, haciendo + llamadas a un kernel más antiguo, el código del kernel debe revisar que + cualquier memoria más allá del tamaño de la estructura sea cero (revisar + de manera efectiva que ``param_4 == 0``). + - Para hacer frente a programas antiguos del userspace haciendo llamadas a + un kernel más nuevo, el código del kernel puede extender con ceros, una + instancia más pequeña de la estructura (definiendo efectivamente + ``param_4 == 0``). + +Revise :manpage:`perf_event_open(2)` y la función ``perf_copy_attr()`` (en +``kernel/events/code.c``) para un ejemplo de esta aproximación. + + +Diseñando el API: Otras consideraciones +--------------------------------------- + +Si su nueva llamada al sistema permite al userspace hacer referencia a un +objeto del kernel, esta debería usar un descriptor de archivo como el +manipulador de ese objeto -- no invente un nuevo tipo de objeto manipulador +userspace cuando el kernel ya tiene mecanismos y semánticas bien definidas +para usar los descriptores de archivos. + +Si su nueva llamada a sistema :manpage:`xyzzy(2)` retorna un nuevo +descriptor de archivo, entonces el argumento flag debe incluir un valor que +sea equivalente a definir ``O_CLOEXEC`` en el nuevo FD. Esto hace posible +al userspace acortar la brecha de tiempo entre ``xyzzy()`` y la llamada a +``fcntl(fd, F_SETFD, FD_CLOEXEC)``, donde un ``fork()`` inesperado y +``execve()`` en otro hilo podrían filtrar un descriptor al programa +ejecutado. (Sin embargo, resista la tentación de reusar el valor actual de +la constante ``O_CLOEXEC``, ya que es específica de la arquitectura y es +parte de un espacio numerado de flags ``O_*`` que está bastante lleno.) + +Si su llamada de sistema retorna un nuevo descriptor de archivo, debería +considerar también que significa usar la familia de llamadas de sistema +:manpage:`poll(2)` en ese descriptor de archivo. Hacer un descriptor de +archivo listo para leer o escribir es la forma normal para que el kernel +indique al espacio de usuario que un evento ha ocurrido en el +correspondiente objeto del kernel. + +Si su nueva llamada de sistema :manpage:`xyzzy(2)` involucra algún nombre +de archivo como argumento:: + + int sys_xyzzy(const char __user *path, ..., unsigned int flags); + +debería considerar también si una versión :manpage:`xyzzyat(2)` es mas +apropiada:: + + int sys_xyzzyat(int dfd, const char __user *path, ..., unsigned int flags); + +Esto permite más flexibilidad en como el userspace especifica el archivo en +cuestión; en particular esto permite al userspace pedir la funcionalidad a +un descriptor de archivo ya abierto usando el flag ``AT_EMPTY_PATH``, +efectivamente dando una operación :manpage:`fxyzzy(3)` gratis:: + + - xyzzyat(AT_FDCWD, path, ..., 0) es equivalente a xyzzy(path, ...) + - xyzzyat(fd, "", ..., AT_EMPTY_PATH) es equivalente a fxyzzy(fd, ...) + +(Para más detalles sobre la explicación racional de las llamadas \*at(), +revise el man page :manpage:`openat(2)`; para un ejemplo de AT_EMPTY_PATH, +mire el man page :manpage:`fstatat(2)` manpage.) + +Si su nueva llamada de sistema :manpage:`xyzzy(2)` involucra un parámetro +describiendo un describiendo un movimiento dentro de un archivo, ponga de +tipo ``loff_t`` para que movimientos de 64-bit puedan ser soportados +incluso en arquitecturas de 32-bit. + +Si su nueva llamada de sistema :manpage:`xyzzy` involucra una +funcionalidad privilegiada, esta necesita ser gobernada por la capability +bit linux apropiada (revisado con una llamada a ``capable()``), como se +describe en el man page :manpage:`capabilities(7)`. Elija una parte de +capability linux que govierne las funcionalidades relacionadas, pero trate +de evitar combinar muchas funciones sólo relacionadas vagamente bajo la +misma sección, ya que va en contra de los propósitos de las capabilities de +dividir el poder del usuario root. En particular, evite agregar nuevos usos +de la capacidad ya demasiado general de la capabilities ``CAP_SYS_ADMIN``. + +Si su nueva llamada de sistema :manpage:`xyzzy(2)` manipula un proceso que +no es el proceso invocado, este debería ser restringido (usando una llamada +a ``ptrace_may_access()``) de forma que el único proceso con los mismos +permisos del proceso objetivo, o con las capacidades (capabilities) +necesarias, pueda manipulador el proceso objetivo. + +Finalmente, debe ser conciente de que algunas arquitecturas no-x86 tienen +un manejo más sencillo si los parámetros que son explícitamente 64-bit +caigan en argumentos enumerados impares (i.e. parámetros 1,3,5), para +permitir el uso de pares contiguos de registros 32-bits. (Este cuidado no +aplica si el argumento es parte de una estructura que se pasa a través de +un puntero.) + +Proponiendo el API +------------------ + +Para hacer una nueva llamada al sistema fácil de revisar, es mejor dividir +el patchset (conjunto de parches) en trozos separados. Estos deberían +incluir al menos los siguientes items como commits distintos (cada uno de +los cuales se describirá más abajo): + + - La implementación central de la llamada al sistema, junto con + prototipos, numeración genérica, cambios Kconfig e implementaciones de + rutinas de respaldo (fallback stub) + - Conectar la nueva llamada a sistema a una arquitectura particular, + usualmente x86 (incluyendo todas las x86_64, x86_32 y x32). + - Una demostración del use de la nueva llamada a sistema en el userspace + vía un selftest en ``tools/testing/selftest/``. + - Un borrador de man-page para la nueva llamada a sistema, ya sea como + texto plano en la carta de presentación, o como un parche (separado) + para el repositorio man-pages. + +Nuevas propuestas de llamadas de sistema, como cualquier cambio al API del +kernel, debería siempre ser copiado a linux-api@vger.kernel.org. + + +Implementation de Llamada de Sistema Generica +--------------------------------------------- + +La entrada principal a su nueva llamada de sistema :manpage:`xyzzy(2)` será +llamada ``sys_xyzzy()``, pero incluya este punto de entrada con la macro +``SYSCALL_DEFINEn()`` apropiada en vez de explicitamente. El 'n' indica el +numero de argumentos de la llamada de sistema, y la macro toma el nombre de +la llamada de sistema seguida por el par (tipo, nombre) para los parámetros +como argumentos. Usar esta macro permite a la metadata de la nueva llamada +de sistema estar disponible para otras herramientas. + +El nuevo punto de entrada también necesita un prototipo de función +correspondiente en ``include/linux/syscalls.h``, marcado como asmlinkage +para calzar en la manera en que las llamadas de sistema son invocadas:: + + asmlinkage long sys_xyzzy(...); + +Algunas arquitecturas (e.g. x86) tienen sus propias tablas de syscall +específicas para la arquitectura, pero muchas otras arquitecturas comparten +una tabla de syscall genéricas. Agrega su nueva llamada de sistema a la +lista genérica agregando una entrada a la lista en +``include/uapi/asm-generic/unistd.h``:: + + #define __NR_xyzzy 292 + __SYSCALL(__NR_xyzzy, sys_xyzzy ) + +También actualice el conteo de __NR_syscalls para reflejar la llamada de +sistema adicional, y note que si multiples llamadas de sistema nuevas son +añadidas en la misma ventana unida, su nueva llamada de sistema podría +tener que ser ajustada para resolver conflictos. + +El archivo ``kernel/sys_ni.c`` provee una implementación fallback stub +(rutina de respaldo) para cada llamada de sistema, retornando ``-ENOSYS``. +Incluya su nueva llamada a sistema aquí también:: + + COND_SYSCALL(xyzzy); + +Su nueva funcionalidad del kernel, y la llamada de sistema que la controla, +debería normalmente ser opcional, así que incluya una opción ``CONFIG`` +(tipicamente en ``init/Kconfig``) para ella. Como es usual para opciones +``CONFIG`` nuevas: + + - Incluya una descripción para la nueva funcionalidad y llamada al sistema + controlada por la opción. + - Haga la opción dependiendo de EXPERT si esta debe estar escondida de los + usuarios normales. + - Haga que cualquier nuevo archivo fuente que implemente la función + dependa de la opción CONFIG en el Makefile (e.g. + ``obj-$(CONFIG_XYZZY_SYSCALL) += xyzzy.o``). + - Revise dos veces que el kernel se siga compilando con la nueva opción + CONFIG apagada. + +Para resumir, necesita un commit que incluya: + + - una opción ``CONFIG`` para la nueva función, normalmente en ``init/Kconfig`` + - ``SYSCALL_DEFINEn(xyzzy, ...)`` para el punto de entrada + - El correspondiente prototipo en ``include/linux/syscalls.h`` + - Una entrada genérica en ``include/uapi/asm-generic/unistd.h`` + - fallback stub en ``kernel/sys_ni.c`` + + +Implementación de Llamada de Sistema x86 +---------------------------------------- + +Para conectar su nueva llamada de sistema a plataformas x86, necesita +actualizar las tablas maestras syscall. Asumiendo que su nueva llamada de +sistema ni es especial de alguna manera (revise abajo), esto involucra una +entrada "común" (para x86_64 y x86_32) en +arch/x86/entry/syscalls/syscall_64.tbl:: + + 333 common xyzz sys_xyzzy + +y una entrada "i386" en ``arch/x86/entry/syscalls/syscall_32.tbl``:: + + 380 i386 xyzz sys_xyzzy + +De nuevo, estos número son propensos de ser cambiados si hay conflictos en +la ventana de integración relevante. + + +Compatibilidad de Llamadas de Sistema (Genérica) +------------------------------------------------ + +Para la mayoría de llamadas al sistema la misma implementación 64-bit puede +ser invocada incluso cuando el programa de userspace es en si mismo 32-bit; +incluso si los parámetros de la llamada de sistema incluyen un puntero +explícito, esto es manipulado de forma transparente. + +Sin embargo, existe un par de situaciones donde se necesita una capa de +compatibilidad para lidiar con las diferencias de tamaño entre 32-bit y +64-bit. + +La primera es si el kernel 64-bit también soporta programas del userspace +32-bit, y por lo tanto necesita analizar areas de memoria del (``__user``) +que podrían tener valores tanto 32-bit como 64-bit. En particular esto se +necesita siempre que un argumento de la llamada a sistema es: + + - un puntero a un puntero + - un puntero a un struc conteniendo un puntero (por ejemplo + ``struct iovec __user *``) + - un puntero a un type entero de tamaño entero variable (``time_t``, + ``off_t``, ``long``, ...) + - un puntero a un struct conteniendo un type entero de tamaño variable. + +La segunda situación que requiere una capa de compatibilidad es cuando uno +de los argumentos de la llamada a sistema tiene un argumento que es +explícitamente 64-bit incluso sobre arquitectura 32-bit, por ejemplo +``loff_t`` o ``__u64``. En este caso, el valor que llega a un kernel 64-bit +desde una aplicación de 32-bit se separará en dos valores de 32-bit, los +que luego necesitan ser reensamblados en la capa de compatibilidad. + +(Note que un argumento de una llamada a sistema que sea un puntero a un +type explicitamente de 64-bit **no** necesita una capa de compatibilidad; +por ejemplo, los argumentos de :manpage:`splice(2)`) del tipo +``loff_t __user *`` no significan la necesidad de una llamada a sistema +``compat_``.) + +La versión compatible de la llamada de sistema se llama +``compat_sys_xyzzy()``, y se agrega con la macro +``COMPAT_SYSCALL_DEFINEn``, de manera análoga a SYSCALL_DEFINEn. Esta +versión de la implementación se ejecuta como parte de un kernel de 64-bit, +pero espera recibir parametros con valores 32-bit y hace lo que tenga que +hacer para tratar con ellos. (Típicamente, la versión ``compat_sys_`` +convierte los valores a versiones de 64 bits y llama a la versión ``sys_`` +o ambas llaman a una función de implementación interna común.) + +El punto de entrada compat también necesita un prototipo de función +correspondiente, en ``include/linux/compat.h``, marcado como asmlinkage +para igualar la forma en que las llamadas al sistema son invocadas:: + + asmlinkage long compat_sys_xyzzy(...); + +Si la nueva llamada al sistema involucra una estructura que que se dispone +de forma distinta en sistema de 32-bit y 64-bit, digamos +``struct xyzzy_args``, entonces el archivo de cabecera +include/linux/compat.h también debería incluir una versión compatible de la +estructura (``struct compat_xyzzy_args``) donde cada campo de tamaño +variable tiene el tipo ``compat_`` apropiado que corresponde al tipo en +``struct xyzzy_args``. La rutina ``compat_sys_xyzzy()`` puede entonces usar +esta estructura ``compat_`` para analizar los argumentos de una invocación +de 32-bit. + +Por ejemplo, si hay campos:: + + struct xyzzy_args { + const char __user *ptr; + __kernel_long_t varying_val; + u64 fixed_val; + /* ... */ + }; + +en struct xyzzy_args, entonces struct compat_xyzzy_args debe tener:: + + struct compat_xyzzy_args { + compat_uptr_t ptr; + compat_long_t varying_val; + u64 fixed_val; + /* ... */ + }; + +la lista genérica de llamadas al sistema también necesita ajustes para +permitir la versión compat; la entrada en +``include/uapi/asm-generic/unistd.h`` debería usar ``__SC_COMP`` en vez de +``__SYSCALL``:: + + #define __NR_xyzzy 292 + __SC_COMP(__NR_xyzzy, sys_xyzzy, compat_sys_xyzzy) + +Para resumir, necesita: + + - una ``COMPAT_SYSCALL_DEFINEn(xyzzy, ...)`` para el punto de entrada de compat. + - el prototipo correspondiente en ``include/linux/compat.h`` + - (en caso de ser necesario) un struct de mapeo de 32-bit en ``include/linux/compat.h`` + - una instancia de ``__SC_COMP`` no ``__SYSCALL`` en ``include/uapi/asm-generic/unistd.h`` + +Compatibilidad de Llamadas de Sistema (x86) +------------------------------------------- + +Para conectar la arquitectura x86 de una llamada al sistema con una versión +de compatibilidad, las entradas en las tablas de syscall deben ser +ajustadas. + +Primero, la entrada en ``arch/x86/entry/syscalls/syscall_32.tbl`` recibe +una columna extra para indicar que un programa del userspace de 32-bit +corriendo en un kernel de 64-bit debe llegar al punto de entrada compat:: + + 380 i386 xyzzy sys_xyzzy __ia32_compat_sys_xyzzy + +Segundo, tienes que averiguar qué debería pasar para la versión x32 ABI de +la nueva llamada al sistema. Aquí hay una elección: el diseño de los +argumentos debería coincidir con la versión de 64-bit o la versión de +32-bit. + +Si hay involucrado un puntero-a-puntero, la decisión es fácil: x32 es +ILP32, por lo que el diseño debe coincidir con la versión 32-bit, y la +entrada en ``arch/x86/entry/syscalls/syscall_64.tbl`` se divide para que +progamas 32-bit lleguen al envoltorio de compatibilidad:: + + 333 64 xyzzy sys_xyzzy + ... + 555 x32 xyzzy __x32_compat_sys_xyzzy + +Si no hay punteros involucrados, entonces es preferible reutilizar el system +call 64-bit para el x32 ABI (y consecuentemente la entrada en +arch/x86/entry/syscalls/syscall_64.tbl no se cambia). + +En cualquier caso, debes revisar que lo tipos involucrados en su diseño de +argumentos de hecho asigne exactamente de x32 (-mx32) a 32-bit(-m32) o +equivalentes 64-bit (-m64). + + +Llamadas de Sistema Retornando a Otros Lugares +---------------------------------------------- + +Para la mayoría de las llamadas al sistema, una vez que se la llamada al +sistema se ha completado el programa de usuario continúa exactamente donde +quedó -- en la siguiente instrucción, con el stack igual y la mayoría de +los registros igual que antes de la llamada al sistema, y con el mismo +espacio en la memoria virtual. + +Sin embargo, unas pocas llamadas al sistema hacen las cosas diferente. +Estas podrían retornar a una ubicación distinta (``rt_sigreturn``) o +cambiar el espacio de memoria (``fork``/``vfork``/``clone``) o incluso de +arquitectura (``execve``/``execveat``) del programa. + +Para permitir esto, la implementación del kernel de la llamada al sistema +podría necesitar guardar y restaurar registros adicionales al stak del +kernel, brindandole control completo de donde y cómo la ejecución continúa +después de la llamada a sistema. + +Esto es arch-specific, pero típicamente involucra definir puntos de entrada +assembly que guardan/restauran registros adicionales e invocan el punto de +entrada real de la llamada a sistema. + +Para x86_64, esto es implementado como un punto de entrada ``stub_xyzzy`` +en ``arch/x86/entry/entry_64.S``, y la entrada en la tabla syscall +(``arch/x86/entry/syscalls/syscall_32.tbl``) es ajustada para calzar:: + + 333 common xyzzy stub_xyzzy + +El equivalente para programas 32-bit corriendo en un kernel 64-bit es +normalmente llamado ``stub32_xyzzy`` e implementado en +``arch/x86/entry/entry_64_compat.S``, con el correspondiente ajuste en la +tabla syscall en ``arch/x86/syscalls/syscall_32.tbl``:: + + 380 i386 xyzzy sys_xyzzy stub32_xyzzy + +Si la llamada a sistema necesita una capa de compatibilidad (como en la +sección anterior) entonces la versión ``stub32_`` necesita llamar a la +versión ``compat_sys_`` de la llamada a sistema, en vez de la versión +nativa de 64-bit. También, si la implementación de la versión x32 ABI no es +comun con la versión x86_64, entonces su tabla syscall también necesitará +invocar un stub que llame a la versión ``compat_sys_`` + +Para completar, también es agradable configurar un mapeo de modo que el +user-mode linux todavía funcione -- su tabla syscall referenciará +stub_xyzzy, pero el UML construido no incluye una implementación +``arch/x86/entry/entry_64.S``. Arreglar esto es tan simple como agregar un +#define a ``arch/x86/um/sys_call_table_64.c``:: + + #define stub_xyzzy sys_xyzzy + + +Otros detalles +-------------- + +La mayoría del kernel trata las llamadas a sistema de manera genérica, pero +está la excepción ocasional que pueda requerir actualización para su +llamada a sistema particular. + +El subsistema de auditoría es un caso especial; este incluye funciones +(arch-specific) que clasifican algunos tipos especiales de llamadas al +sistema -- específicamente file open (``open``/``openat``), program +execution (``execve`` /``execveat``) o operaciones multiplexores de socket +(``socketcall``). Si su nueva llamada de sistema es análoga a alguna de +estas, entonces el sistema auditor debe ser actualizado. + +Más generalmente, si existe una llamada al sistema que sea análoga a su +nueva llamada al sistema, entonces vale la pena hacer un grep a todo el +kernel de la llamada a sistema existente, para revisar que no exista otro +caso especial. + + +Testing +------- + +Una nueva llamada al sistema debe obviamente ser probada; también es útil +proveer a los revisores con una demostración de cómo los programas del +userspace usarán la llamada al sistema. Una buena forma de combinar estos +objetivos es incluir un simple programa self-test en un nuevo directorio +bajo ``tools/testing/selftests/``. + +Para una nueva llamada al sistema, obviamente no habrá una función +envoltorio libc por lo que el test necesitará ser invocado usando +``syscall()``; también, si la llamada al sistema involucra una nueva +estructura userspace-visible, el encabezado correspondiente necesitará ser +instalado para compilar el test. + +Asegure que selftest corra satisfactoriamente en todas las arquitecturas +soportadas. Por ejemplo, revise si funciona cuando es compilado como un +x86_64 (-m64), x86_32 (-m32) y x32 (-mx32) programa ABI. + +Para pruebas más amplias y exhautivas de la nueva funcionalidad, también +debería considerar agregar tests al Linus Test Project, o al proyecto +xfstests para cambios filesystem-related + + - https://linux-test-project.github.io/ + - git://git.kernel.org/pub/scm/fs/xfs/xfstests-dev.git + + +Man Page +-------- + +Todas las llamada al sistema nueva deben venir con un man page completo, +idealmente usando groff markup, pero texto plano también funciona. Si se +usa groff, es útil incluir una versión ASCII pre-renderizada del man-page +en el cover del email para el patchset, para la conveniencia de los +revisores. + +El man page debe ser cc'do a linux-man@vger.kernel.org +Para más detalles, revise https://www.kernel.org/doc/man-pages/patches.html + + +No invoque las llamadas de sistemas en el kernel +------------------------------------------------ + +Las llamadas al sistema son, cómo se declaró más arriba, puntos de +interacción entre el userspace y el kernel. Por lo tanto, las funciones de +llamada al sistema como ``sys_xyzzy()`` o ``compat_sys_xyzzy()`` deberían +ser llamadas sólo desde el userspace vía la tabla de syscall, pero no de +otro lugar en el kernel. Si la funcionalidad syscall es útil para ser usada +dentro del kernel, necesita ser compartida entre syscalls nuevas o +antiguas, o necesita ser compartida entre una syscall y su variante de +compatibilidad, esta debería ser implementada mediante una función "helper" +(como ``ksys_xyzzy()``). Esta función del kernel puede ahora ser llamada +dentro del syscall stub (``sys_xyzzy()``), la syscall stub de +compatibilidad (``compat_sys_xyzzy()``), y/o otro código del kernel. + +Al menos en 64-bit x86, será un requerimiento duro desde la v4.17 en +adelante no invocar funciones de llamada al sistema (system call) en el +kernel. Este usa una convención de llamada diferente para llamadas al +sistema donde ``struct pt_regs`` es decodificado on-the-fly en un +envoltorio syscall que luego entrega el procesamiento al syscall real. Esto +significa que sólo aquellos parámetros que son realmente necesarios para +una syscall específica son pasados durante la entrada del syscall, en vez +de llenar en seis registros de CPU con contenido random del userspace todo +el tiempo (los cuales podrían causar serios problemas bajando la cadena de +llamadas). + +Más aún, reglas sobre cómo se debería acceder a la data pueden diferir +entre la data del kernel y la data de usuario. Esta es otra razón por la +cual llamar a ``sys_xyzzy()`` es generalmente una mala idea. + +Excepciones a esta regla están permitidas solamente en overrides +específicos de arquitectura, envoltorios de compatibilidad específicos de +arquitectura, u otro código en arch/. + + +Referencias y fuentes +--------------------- + + - Artículo LWN de Michael Kerrisk sobre el uso de argumentos flags en llamadas al + sistema: + https://lwn.net/Articles/585415/ + - Artículo LWN de Michael Kerrisk sobre cómo manejar flags desconocidos en una + llamada al sistema: https://lwn.net/Articles/588444/ + - Artículo LWN de Jake Edge describiendo restricciones en argumentos en + 64-bit system call: https://lwn.net/Articles/311630/ + - Par de artículos LWN de David Drysdale que describen la ruta de implementación + de llamadas al sistema en detalle para v3.14: + + - https://lwn.net/Articles/604287/ + - https://lwn.net/Articles/604515/ + + - Requerimientos arquitectura-específicos para llamadas al sistema son discutidos en el + :manpage:`syscall(2)` man-page: + http://man7.org/linux/man-pages/man2/syscall.2.html#NOTES + - Recopilación de emails de Linus Torvalds discutiendo problemas con ``ioctl()``: + https://yarchive.net/comp/linux/ioctl.html + - "How to not invent kernel interfaces", Arnd Bergmann, + https://www.ukuug.org/events/linux2007/2007/papers/Bergmann.pdf + - Artículo LWN de Michael Kerrisk sobre evitar nuevos usos de CAP_SYS_ADMIN: + https://lwn.net/Articles/486306/ + - Recomendaciones de Andrew Morton que toda la información relacionada a una nueva + llamada al sistema debe venir en el mismo hilo de correos: + https://lore.kernel.org/r/20140724144747.3041b208832bbdf9fbce5d96@linux-foundation.org + - Recomendaciones de Michael Kerrisk que una nueva llamada al sistema debe venir + con un man-page: https://lore.kernel.org/r/CAKgNAkgMA39AfoSoA5Pe1r9N+ZzfYQNvNPvcRN7tOvRb8+v06Q@mail.gmail.com + - Sugerencias de Thomas Gleixner que conexiones x86 deben ir en commits + separados: https://lore.kernel.org/r/alpine.DEB.2.11.1411191249560.3909@nanos + - Sugerencias de Greg Kroah-Hartman que es bueno para las nueva llamadas al sistema + que vengan con man-page y selftest: https://lore.kernel.org/r/20140320025530.GA25469@kroah.com + - Discusión de Michael Kerrisk de nuevas system call vs. extensiones :manpage:`prctl(2)`: + https://lore.kernel.org/r/CAHO5Pa3F2MjfTtfNxa8LbnkeeU8=YJ+9tDqxZpw7Gz59E-4AUg@mail.gmail.com + - Sugerencias de Ingo Molnar que llamadas al sistema que involucran múltiples + argumentos deben encapsular estos argumentos en una estructura, la cual incluye + un campo de tamaño para futura extensibilidad: https://lore.kernel.org/r/20150730083831.GA22182@gmail.com + - Enumerando rarezas por la (re-)utilización de O_* numbering space flags: + + - commit 75069f2b5bfb ("vfs: renumber FMODE_NONOTIFY and add to uniqueness + check") + - commit 12ed2e36c98a ("fanotify: FMODE_NONOTIFY and __O_SYNC in sparc + conflict") + - commit bb458c644a59 ("Safer ABI for O_TMPFILE") + + - Discusión de Matthew Wilcox sobre las restricciones en argumentos 64-bit: + https://lore.kernel.org/r/20081212152929.GM26095@parisc-linux.org + - Recomendaciones de Greg Kroah-Hartman sobre flags desconocidos deben ser + vigilados: https://lore.kernel.org/r/20140717193330.GB4703@kroah.com + - Recomendaciones de Linus Torvalds que las llamadas al sistema x32 deben favorecer + compatibilidad con versiones 64-bit sobre versiones 32-bit: + https://lore.kernel.org/r/CA+55aFxfmwfB7jbbrXxa=K7VBYPfAvmu3XOkGrLbB1UFjX1+Ew@mail.gmail.com diff --git a/Documentation/translations/sp_SP/process/code-of-conduct.rst b/Documentation/translations/sp_SP/process/code-of-conduct.rst new file mode 100644 index 000000000..adc6c770c --- /dev/null +++ b/Documentation/translations/sp_SP/process/code-of-conduct.rst @@ -0,0 +1,97 @@ +.. include:: ../disclaimer-sp.rst + +:Original: :ref:`Documentation/process/code-of-conduct.rst <code_of_conduct>` +:Translator: Contributor Covenant and Carlos Bilbao <carlos.bilbao@amd.com> + +.. _sp_code_of_conduct: + +Código de Conducta para Contribuyentes ++++++++++++++++++++++++++++++++++++++++ + +Nuestro Compromiso +================== + +Nosotros, como miembros, contribuyentes y administradores nos comprometemos +a hacer de la participación en nuestra comunidad una experiencia libre de +acoso para todo el mundo, independientemente de la edad, dimensión corporal, +minusvalía visible o invisible, etnicidad, características sexuales, +identidad y expresión de género, nivel de experiencia, educación, nivel +socio-económico, nacionalidad, apariencia personal, raza, religión, o +identidad u orientación sexual. Nos comprometemos a actuar e interactuar de +maneras que contribuyan a una comunidad abierta, acogedora, diversa, +inclusiva y sana. + +Nuestros Estándares +=================== + +Ejemplos de comportamiento que contribuyen a crear un ambiente positivo +para nuestra comunidad: + +* Demostrar empatía y amabilidad ante otras personas +* Respeto a diferentes opiniones, puntos de vista y experiencias +* Dar y aceptar adecuadamente retroalimentación constructiva +* Aceptar la responsabilidad y disculparse ante quienes se vean afectados + por nuestros errores, aprendiendo de la experiencia +* Centrarse en lo que sea mejor no sólo para nosotros como individuos, sino + para la comunidad en general + + +Ejemplos de comportamiento inaceptable: + +* El uso de lenguaje o imágenes sexualizadas, y aproximaciones o + atenciones sexuales de cualquier tipo +* Comentarios despectivos (trolling), insultantes o derogatorios, y ataques + personales o políticos +* El acoso en público o privado +* Publicar información privada de otras personas, tales como direcciones + físicas o de correo + electrónico, sin su permiso explícito +* Otras conductas que puedan ser razonablemente consideradas como + inapropiadas en un entorno profesional + + +Aplicación de las responsabilidades +=================================== + +Los administradores de la comunidad son responsables de aclarar y hacer +cumplir nuestros estándares de comportamiento aceptable y tomarán acciones +apropiadas y correctivas de forma justa en respuesta a cualquier +comportamiento que consideren inapropiado, amenazante, ofensivo o dañino. + +Los administradores de la comunidad tendrán el derecho y la responsabilidad +de eliminar, editar o rechazar comentarios, commits, código, ediciones de +páginas de wiki, issues y otras contribuciones que no se alineen con este +Código de Conducta, y comunicarán las razones para sus decisiones de +moderación cuando sea apropiado. + +Alcance +======= + +Este código de conducta aplica tanto a espacios del proyecto como a +espacios públicos donde un individuo esté en representación del proyecto o +comunidad. Ejemplos de esto incluyen el uso de la cuenta oficial de correo +electrónico, publicaciones a través de las redes sociales oficiales, o +presentaciones con personas designadas en eventos en línea o no. + +Aplicación +========== + +Instancias de comportamiento abusivo, acosador o inaceptable de otro modo +podrán ser reportadas contactando el Code of Conduct Commitee a través de +<conduct@kernel.org>. Todas las quejas serán evaluadas e investigadas de +una manera puntual y justa. El Code of Condut Commitee está obligados a +respetar la privacidad y la seguridad de quienes reporten incidentes. +Detalles de políticas y aplicación en particular, serán incluidos por +separado. + +Atribución +========== + +Este Código de Conducta es una adaptación del Contributor Covenant, versión +1.4, disponible en https://www.contributor-covenant.org/version/1/4/code-of-conduct.html + +Interpretación +============== + +Consulte el documento :ref:`code_of_conduct_interpretation` para ver cómo +interpretará la comunidad del kernel Linux este documento. diff --git a/Documentation/translations/sp_SP/process/coding-style.rst b/Documentation/translations/sp_SP/process/coding-style.rst new file mode 100644 index 000000000..a0261ba5b --- /dev/null +++ b/Documentation/translations/sp_SP/process/coding-style.rst @@ -0,0 +1,1315 @@ +.. include:: ../disclaimer-sp.rst + +:Original: :ref:`Documentation/process/coding-style.rst <submittingpatches>` +:Translator: Carlos Bilbao <carlos.bilbao@amd.com> + +.. _sp_codingstyle: + +Estilo en el código del kernel Linux +===================================== + +Este es un breve documento que describe el estilo preferido en el código +del kernel Linux. El estilo de código es muy personal y no **forzaré** mi +puntos de vista sobre nadie, pero esto vale para todo lo que tengo que +mantener, y preferiría que para la mayoría de otras cosas también. Por +favor, por lo menos considere los argumentos expuestos aquí. + +En primer lugar, sugeriría imprimir una copia de los estándares de código +GNU, y NO leerlo. Quémelos, es un gran gesto simbólico. + +De todos modos, aquí va: + + +1) Sangría +----------- + +Las tabulaciones tienen 8 caracteres y, por lo tanto, las sangrías también +tienen 8 caracteres. Hay movimientos heréticos que intentan hacer sangría +de 4 (¡o incluso 2!) caracteres de longitud, y eso es similar a tratar de +definir el valor de PI como 3. + +Justificación: La idea detrás de la sangría es definir claramente dónde +comienza y termina un bloque de control. Especialmente, cuando ha estado +buscando en su pantalla durante 20 horas seguidas, le resultará mucho más +fácil ver cómo funciona la sangría si tiene sangrías grandes. + +Bueno, algunas personas dirán que tener sangrías de 8 caracteres hace que +el código se mueva demasiado a la derecha y dificulta la lectura en una +pantalla de terminal de 80 caracteres. La respuesta a eso es que si +necesita más de 3 niveles de sangría, está en apuros de todos modos y +debería arreglar su programa. + +En resumen, las sangrías de 8 caracteres facilitan la lectura y tienen la +ventaja añadida de advertirle cuando está anidando sus funciones demasiado +profundo. Preste atención a esa advertencia. + +La forma preferida de facilitar múltiples niveles de sangría en una +declaración de switch es para alinear el ``switch`` y sus etiquetas +``case`` subordinadas en la misma columna, en lugar de hacer ``doble +sangría`` (``double-indenting``) en etiquetas ``case``. Por ejemplo: + +.. code-block:: c + + switch (suffix) { + case 'G': + case 'g': + mem <<= 30; + break; + case 'M': + case 'm': + mem <<= 20; + break; + case 'K': + case 'k': + mem <<= 10; + fallthrough; + default: + break; + } + +No ponga varias declaraciones en una sola línea a menos que tenga algo que +ocultar: + +.. code-block:: c + + if (condición) haz_esto; + haz_otra_cosa; + +No use comas para evitar el uso de llaves: + +.. code-block:: c + + if (condición) + haz_esto(), haz_eso(); + +Siempre use llaves para múltiples declaraciones: + +.. code-block:: c + + if (condición) { + haz_esto(); + haz_eso(); + } + +Tampoco ponga varias asignaciones en una sola línea. El estilo de código +del kernel es súper simple. Evite las expresiones engañosas. + + +Aparte de los comentarios, la documentación y excepto en Kconfig, los +espacios nunca se utilizan para la sangría, y el ejemplo anterior se rompe +deliberadamente. + +Consiga un editor decente y no deje espacios en blanco al final de las +líneas. + +2) Rompiendo líneas y strings largos +------------------------------------ + +El estilo de código tiene todo que ver con la legibilidad y la +mantenibilidad usando herramientas disponibles comúnmente. + +El límite preferido en la longitud de una sola línea es de 80 columnas. + +Las declaraciones de más de 80 columnas deben dividirse en partes, a menos +que exceder las 80 columnas aumente significativamente la legibilidad y no +oculte información. + +Los descendientes siempre son sustancialmente más cortos que el padre y +se colocan sustancialmente a la derecha. Un estilo muy usado es alinear +descendientes a un paréntesis de función abierto. + +Estas mismas reglas se aplican a los encabezados de funciones con una larga +lista de argumentos. + +Sin embargo, nunca rompa los strings visibles para el usuario, como los +mensajes printk, porque eso rompe la capacidad de grep a estos. + + +3) Colocación de llaves y espacios +---------------------------------- + +El otro problema que siempre surge en el estilo C es la colocación de +llaves. A diferencia del tamaño de la sangría, existen pocas razones +técnicas para elegir una estrategia de ubicación sobre la otra, pero la +forma preferida, como mostraron los profetas Kernighan y Ritchie, es poner +la llave de apertura en la línea, y colocar la llave de cierre primero, +así: + +.. code-block:: c + + if (x es verdad) { + hacemos y + } + +Esto se aplica a todos los bloques de declaraciones que no son funciones +(if, switch, for, while, do). Por ejemplo: + +.. code-block:: c + + switch (action) { + case KOBJ_ADD: + return "add"; + case KOBJ_REMOVE: + return "remove"; + case KOBJ_CHANGE: + return "change"; + default: + return NULL; + } + +Sin embargo, hay un caso especial, a saber, las funciones: tienen la llave +de apertura al comienzo de la siguiente línea, así: + +.. code-block:: c + + int funcion(int x) + { + cuerpo de la función + } + +Gente hereje de todo el mundo ha afirmado que esta inconsistencia es... +bueno... inconsistente, pero todas las personas sensatas saben que +(a) K&R tienen **razón** y (b) K&R tienen razón. Además, las funciones son +especiales de todos modos (no puede anidarlas en C). + +Tenga en cuenta que la llave de cierre está vacía en su línea propia, +**excepto** en los casos en que es seguida por una continuación de la misma +declaración, es decir, un ``while`` en una sentencia do o un ``else`` en +una sentencia if, como en: + +.. code-block:: c + + do { + cuerpo del bucle do + } while (condition); + +y + +.. code-block:: c + + if (x == y) { + .. + } else if (x > y) { + ... + } else { + .... + } + +Justificación: K&R. + +Además, tenga en cuenta que esta colocación de llaves también minimiza el +número de líneas vacías (o casi vacías), sin pérdida de legibilidad. Así, +como el suministro de nuevas líneas en su pantalla no es un recurso +renovable (piense en pantallas de terminal de 25 líneas), tienes más líneas +vacías para poner comentarios. + +No use llaves innecesariamente donde una sola declaración sea suficiente. + +.. code-block:: c + + if (condition) + accion(); + +y + +.. code-block:: none + + if (condición) + haz_esto(); + else + haz_eso(); + +Esto no aplica si solo una rama de una declaración condicional es una sola +declaración; en este último caso utilice llaves en ambas ramas: + +.. code-block:: c + + if (condición) { + haz_esto(); + haz_eso(); + } else { + en_otro_caso(); + } + +Además, use llaves cuando un bucle contenga más de una declaración simple: + +.. code-block:: c + + while (condición) { + if (test) + haz_eso(); + } + +3.1) Espacios +************* + +El estilo del kernel Linux para el uso de espacios depende (principalmente) +del uso de función versus uso de palabra clave. Utilice un espacio después +de (la mayoría de) las palabras clave. Las excepciones notables son sizeof, +typeof, alignof y __attribute__, que parecen algo así como funciones (y +generalmente se usan con paréntesis en Linux, aunque no son requeridos en +el idioma, como en: ``sizeof info`` después de que ``struct fileinfo info;`` +se declare). + +Así que use un espacio después de estas palabras clave:: + + if, switch, case, for, do, while + +pero no con sizeof, typeof, alignof, o __attribute__. Por ejemplo, + +.. code-block:: c + + + s = sizeof(struct file); + +No agregue espacios alrededor (dentro) de expresiones entre paréntesis. +Este ejemplo es **malo**: + +.. code-block:: c + + + s = sizeof( struct file ); + +Al declarar datos de puntero o una función que devuelve un tipo de puntero, +el uso preferido de ``*`` es adyacente al nombre del dato o nombre de la +función y no junto al nombre del tipo. Ejemplos: + +.. code-block:: c + + + char *linux_banner; + unsigned long long memparse(char *ptr, char **retptr); + char *match_strdup(substring_t *s); + +Use un espacio alrededor (a cada lado de) la mayoría de los operadores +binarios y ternarios, como cualquiera de estos:: + + = + - < > * / % | & ^ <= >= == != ? : + +pero sin espacio después de los operadores unarios:: + + & * + - ~ ! sizeof typeof alignof __attribute__ defined + +sin espacio antes de los operadores unarios de incremento y decremento del +sufijo:: + + ++ -- + +y sin espacio alrededor de los operadores de miembros de estructura ``.`` y +``->``. + +No deje espacios en blanco al final de las líneas. Algunos editores con +``inteligente`` sangría insertarán espacios en blanco al comienzo de las +nuevas líneas como sea apropiado, para que pueda comenzar a escribir la +siguiente línea de código de inmediato. Sin embargo, algunos de estos +editores no eliminan los espacios en blanco si finalmente no termina +poniendo una línea de código allí, como si dejara una línea en blanco. Como +resultado, termina con líneas que contienen espacios en blanco al final. + +Git le advertirá sobre los parches que introducen espacios en blanco al +final y puede, opcionalmente, eliminar los espacios en blanco finales por +usted; sin embargo, si se aplica una serie de parches, esto puede hacer que +los parches posteriores de la serie fallen al cambiar sus líneas de +contexto. + + +4) Nomenclatura +--------------- + +C es un lenguaje espartano, y sus convenciones de nomenclatura deberían +seguir su ejemplo. A diferencia de los programadores de Modula-2 y Pascal, +los programadores de C no usan nombres cuquis como +EstaVariableEsUnContadorTemporal. Un programador de C lo llamaría +variable ``tmp``, que es mucho más fácil de escribir, y no es mas difícil +de comprender. + +SIN EMBARGO, mientras que los nombres de mayúsculas y minúsculas están mal +vistos, los nombres descriptivos para las variables globales son +imprescindibles. Llamar a una función global ``foo`` es un delito. + +Una variable GLOBAL (para usar solo si **realmente** las necesita) necesita +tener un nombre descriptivo, al igual que las funciones globales. Si tiene +una función que cuenta el número de usuarios activos, debe llamar a esta +``contar_usuarios_activos()`` o similar, **no** debe llamarlo ``cntusr()``. + +Codificar el tipo de una función en el nombre (lo llamado notación húngara) +es estúpido: el compilador conoce los tipos de todos modos y puede +verificar estos, y solo confunde al programador. + +Los nombres de las variables LOCALES deben ser breves y directos. Si usted +tiene algún contador aleatorio de tipo entero, probablemente debería +llamarse ``i``. Llamarlo ``loop_counter`` no es productivo, si no hay +posibilidad de ser mal entendido. De manera similar, ``tmp`` puede ser casi +cualquier tipo de variable que se utiliza para contener un valor temporal. + +Si tiene miedo de mezclar los nombres de las variables locales, tiene otro +problema, que se denomina síndrome de +función-crecimiento-desequilibrio-de-hormona. Vea el capítulo 6 (Funciones). + +Para nombres de símbolos y documentación, evite introducir nuevos usos de +'master / slave' (maestro / esclavo) (o 'slave' independientemente de +'master') y 'lista negra / lista blanca' (backlist / whitelist). + +Los reemplazos recomendados para 'maestro / esclavo' son: + '{primary,main} / {secondary,replica,subordinate}' + '{initiator,requester} / {target,responder}' + '{controller,host} / {device,worker,proxy}' + 'leader / follower' + 'director / performer' + +Los reemplazos recomendados para 'backlist / whitelist' son: + 'denylist / allowlist' + 'blocklist / passlist' + +Las excepciones para la introducción de nuevos usos son mantener en espacio +de usuario una ABI/API, o al actualizar la especificación del código de un +hardware o protocolo existente (a partir de 2020) que requiere esos +términos. Para nuevas especificaciones, traduzca el uso de la terminología +de la especificación al estándar de código del kernel donde sea posible. + +5) Typedefs +----------- + +Por favor no use cosas como ``vps_t``. +Es un **error** usar typedef para estructuras y punteros. cuando ve un + +.. code-block:: c + + + vps_t a; + +en el código fuente, ¿qué significa? +En cambio, si dice + +.. code-block:: c + + struct virtual_container *a; + +puede decir qué es ``a`` en realidad. + +Mucha gente piensa que los typedefs ``ayudan a la legibilidad``. No. Son +útiles solamente para: + + (a) objetos totalmente opacos (donde el typedef se usa activamente para + **ocultar** cuál es el objeto). + + Ejemplo: ``pte_t`` etc. objetos opacos a los que solo puede acceder + usando las funciones de acceso adecuadas. + + .. note:: + + La opacidad y las ``funciones de acceso`` no son buenas por sí + mismas. La razón por la que los tenemos para cosas como pte_t, etc. + es que hay real y absolutamente **cero** información accesible de + forma portátil allí. + + (b) Tipos enteros claros, donde la abstracción **ayuda** a evitar + confusiones, ya sea ``int`` o ``long``. + + u8/u16/u32 son definiciones tipográficas perfectamente correctas + aunque encajan en la categoría (d) mejor que aquí. + + .. note:: + + De nuevo - debe haber una **razón** para esto. si algo es + ``unsigned long``, entonces no hay razón para hacerlo + + typedef unsigned long mis_flags_t; + + pero si hay una razón clara de por qué bajo ciertas circunstancias + podría ser un ``unsigned int`` y bajo otras configuraciones podría + ser ``unsigned long``, entonces, sin duda, adelante y use un typedef. + + (c) cuando lo use para crear literalmente un tipo **nuevo** para + comprobación de tipos. + + (d) Nuevos tipos que son idénticos a los tipos estándar C99, en ciertas + circunstancias excepcionales. + + Aunque sólo costaría un corto período de tiempo para los ojos y + cerebro para acostumbrarse a los tipos estándar como ``uint32_t``, + algunas personas se oponen a su uso de todos modos. + + Por lo tanto, los tipos ``u8/u16/u32/u64`` específicos de Linux y sus + equivalentes con signo, que son idénticos a los tipos estándar son + permitidos, aunque no son obligatorios en el nuevo código de su + elección. + + Al editar código existente que ya usa uno u otro conjunto de tipos, + debe ajustarse a las opciones existentes en ese código. + + (e) Tipos seguros para usar en el espacio de usuario. + + En ciertas estructuras que son visibles para el espacio de usuario, no + podemos requerir tipos C99 y o utilizat el ``u32`` anterior. Por lo + tanto, usamos __u32 y tipos similares en todas las estructuras que se + comparten con espacio de usuario. + +Tal vez también haya otros casos, pero la regla básicamente debería ser +NUNCA JAMÁS use un typedef a menos que pueda coincidir claramente con una +de estas reglas. + +En general, un puntero o una estructura que tiene elementos que pueden +ser razonablemente accedidos directamente, **nunca** deben ser un typedef. + +6) Funciones +------------ + +Las funciones deben ser cortas y dulces, y hacer una sola cosa. Deberían +caber en una o dos pantallas de texto (el tamaño de pantalla ISO/ANSI es +80x24, como todos sabemos), y hacer una cosa y hacerla bien. + +La longitud máxima de una función es inversamente proporcional a la +complejidad y el nivel de sangría de esa función. Entonces, si tiene una +función conceptualmente simple que es solo una larga (pero simple) +declaración de case, donde tiene que hacer un montón de pequeñas cosas para +un montón de diferentes casos, está bien tener una función más larga. + +Sin embargo, si tiene una función compleja y sospecha que un estudiante de +primer año de secundaria menos que dotado podría no comprender de qué se +trata la función, debe adherirse a los límites máximos tanto más de +cerca. Use funciones auxiliares con nombres descriptivos (puede pedirle al +compilador que los alinee si cree que es crítico para el rendimiento, y +probablemente lo hará mejor de lo que usted hubiera hecho). + +Otra medida de la función es el número de variables locales. Estas no deben +exceder de 5 a 10, o está haciendo algo mal. Piense de nuevo en la función +y divida en partes más pequeñas. Un cerebro humano puede generalmente +realiza un seguimiento de aproximadamente 7 cosas diferentes, cualquier +elemento más y se confunde. Usted sabe que es brillante, pero tal vez le +gustaría entender lo que hizo dentro de 2 semanas. + +En los archivos fuente, separe las funciones con una línea en blanco. Si la +función es exportada, la macro **EXPORT** debería ponerse inmediatamente +después de la función de cierre de línea de llave. Por ejemplo: + +.. code-block:: c + + int sistema_corriendo(void) + { + return estado_sistema == SISTEMA_CORRIENDO; + } + EXPORT_SYMBOL(sistema_corriendo); + +6.1) Prototipos de funciones +**************************** + +En los prototipos de funciones, incluya nombres de parámetros con sus tipos +de datos. Aunque esto no es requerido por el lenguaje C, se prefiere en +Linux porque es una forma sencilla de añadir información valiosa para el +lector. + +No utilice la palabra clave ``extern`` con declaraciones de función ya que +esto hace las líneas más largas y no es estrictamente necesario. + +Al escribir prototipos de funciones, mantenga el `orden de los elementos regular +<https://lore.kernel.org/mm-commits/CAHk-=wiOCLRny5aifWNhr621kYrJwhfURsa0vFPeUEm8mF0ufg@mail.gmail.com/>`_. +Por ejemplo, usando este ejemplo de declaración de función:: + + __init void * __must_check action(enum magic value, size_t size, u8 count, + char *fmt, ...) __printf(4, 5) __malloc; + +El orden preferido de elementos para un prototipo de función es: + +- clase de almacenamiento (a continuación, ``static __always_inline``, + teniendo en cuenta que ``__always_inline`` es técnicamente un atributo + pero se trata como ``inline``) +- atributos de clase de almacenamiento (aquí, ``__init`` -- es decir, + declaraciones de sección, pero también cosas como ``__cold``) +- tipo de retorno (aquí, ``void *``) +- atributos de tipo de retorno (aquí, ``__must_check``) +- nombre de la función (aquí, ``action``) +- parámetros de la función (aquí, ``(enum magic value, size_t size, u8 count, char *fmt, ...)``, + teniendo en cuenta que los nombres de los parámetros siempre deben + incluirse) +- atributos de parámetros de función (aquí, ``__printf(4, 5)``) +- atributos de comportamiento de la función (aquí, ``__malloc``) + +Tenga en cuenta que para una **definición** de función (es decir, el cuerpo +real de la función), el compilador no permite atributos de parámetros de +función después de parámetros de la función. En estos casos, deberán ir +tras los atributos de clase (por ejemplo, tenga en cuenta el cambio de +posición de ``__printf(4, 5)`` a continuación, en comparación con el +ejemplo de **declaración** anterior):: + + static __always_inline __init __printf(4, 5) void * __must_check action(enum magic value, + size_t size, u8 count, char *fmt, ...) __malloc + { + ... + } + +7) Salida centralizada de funciones +----------------------------------- + +Aunque desaprobado por algunas personas, el equivalente de la instrucción +goto es utilizado con frecuencia por los compiladores, en forma de +instrucción de salto incondicional. + +La declaración goto es útil cuando una función sale desde múltiples +ubicaciones y se deben realizar algunos trabajos comunes, como la limpieza. +Si no se necesita limpieza, entonces simplemente haga return directamente. + +Elija nombres de etiquetas que digan qué hace el goto o por qué existe el +goto. Un ejemplo de un buen nombre podría ser ``out_free_buffer:`` +(``salida_liberar_buffer``) si al irse libera ``buffer``. Evite usar +nombres GW-BASIC como ``err1:`` y ``err2:``, ya que tendría que volver a +numerarlos si alguna vez agrega o elimina rutas de salida, y hacen que sea +difícil de verificar que sean correctos, de todos modos. + +La razón para usar gotos es: + +- Las declaraciones incondicionales son más fáciles de entender y seguir. +- se reduce el anidamiento +- errores al no actualizar los puntos de salida individuales al hacer + modificaciones son evitados +- ahorra el trabajo del compilador de optimizar código redundante ;) + +.. code-block:: c + + int fun(int a) + { + int result = 0; + char *buffer; + + buffer = kmalloc(SIZE, GFP_KERNEL); + if (!buffer) + return -ENOMEM; + + if (condition1) { + while (loop1) { + ... + } + result = 1; + goto out_free_buffer; + } + ... + out_free_buffer: + kfree(buffer); + return result; + } + +Un tipo común de error a tener en cuenta es "un error de error" que es algo +así: + +.. code-block:: c + + err: + kfree(foo->bar); + kfree(foo); + return ret; + +El error en este código es que en algunas rutas de salida, ``foo`` es NULL. +Normalmente la solución para esto es dividirlo en dos etiquetas de error +``err_free_bar:`` y ``err_free_foo:``: + +.. code-block:: c + + err_free_bar: + kfree(foo->bar); + err_free_foo: + kfree(foo); + return ret; + +Idealmente, debería simular errores para probar todas las rutas de salida. + + +8) Comentarios +-------------- + +Los comentarios son buenos, pero también existe el peligro de comentar +demasiado. NUNCA trate de explicar CÓMO funciona su código en un +comentario: es mucho mejor escribir el código para que el +**funcionamiento** sea obvio y es una pérdida de tiempo explicar código mal +escrito. + +Generalmente, desea que sus comentarios digan QUÉ hace su código, no CÓMO. +Además, trate de evitar poner comentarios dentro del cuerpo de una función: +si la función es tan compleja que necesita comentar por separado partes de +esta, probablemente debería volver al capítulo 6 una temporada. Puede +hacer pequeños comentarios para notar o advertir sobre algo particularmente +inteligente (o feo), pero trate de evitar el exceso. En su lugar, ponga los +comentarios al principio de la función, diga a la gente lo que hace y +posiblemente POR QUÉ hace esto. + +Al comentar las funciones de la API del kernel, utilice el formato +kernel-doc. Consulte los archivos en :ref:`Documentation/doc-guide/ <doc_guide>` +y ``scripts/kernel-doc`` para más detalles. + +El estilo preferido para comentarios largos (de varias líneas) es: + +.. code-block:: c + + /* + * Este es el estilo preferido para comentarios + * multilínea en el código fuente del kernel Linux. + * Por favor, utilícelo constantemente. + * + * Descripción: Una columna de asteriscos en el lado izquierdo, + * con líneas iniciales y finales casi en blanco. + */ + +Para archivos en net/ y drivers/net/, el estilo preferido para comentarios +largos (multi-linea) es un poco diferente. + +.. code-block:: c + + /* El estilo de comentario preferido para archivos en net/ y drivers/net + * se asemeja a esto. + * + * Es casi lo mismo que el estilo de comentario generalmente preferido, + * pero no hay una línea inicial casi en blanco. + */ + +También es importante comentar los datos, ya sean tipos básicos o +derivados. Para este fin, use solo una declaración de datos por línea (sin +comas para múltiples declaraciones de datos). Esto le deja espacio para un +pequeño comentario sobre cada elemento, explicando su uso. + +9) Has hecho un desastre +--------------------------- + +Está bien, todos lo hacemos. Probablemente un antiguo usuario de Unix le +haya dicho que ``GNU emacs`` formatea automáticamente las fuentes C por +usted, y ha notado que sí, lo hace, pero los por defecto que tiene son +menos que deseables (de hecho, son peores que los aleatorios) escribiendo - +un número infinito de monos escribiendo en GNU emacs nunca harán un buen +programa). + +Por lo tanto, puede deshacerse de GNU emacs o cambiarlo y usar valores más +sanos. Para hacer esto último, puede pegar lo siguiente en su archivo +.emacs: + +.. code-block:: none + + (defun c-lineup-arglist-tabs-only (ignored) + "Line up argument lists by tabs, not spaces" + (let* ((anchor (c-langelem-pos c-syntactic-element)) + (column (c-langelem-2nd-pos c-syntactic-element)) + (offset (- (1+ column) anchor)) + (steps (floor offset c-basic-offset))) + (* (max steps 1) + c-basic-offset))) + + (dir-locals-set-class-variables + 'linux-kernel + '((c-mode . ( + (c-basic-offset . 8) + (c-label-minimum-indentation . 0) + (c-offsets-alist . ( + (arglist-close . c-lineup-arglist-tabs-only) + (arglist-cont-nonempty . + (c-lineup-gcc-asm-reg c-lineup-arglist-tabs-only)) + (arglist-intro . +) + (brace-list-intro . +) + (c . c-lineup-C-comments) + (case-label . 0) + (comment-intro . c-lineup-comment) + (cpp-define-intro . +) + (cpp-macro . -1000) + (cpp-macro-cont . +) + (defun-block-intro . +) + (else-clause . 0) + (func-decl-cont . +) + (inclass . +) + (inher-cont . c-lineup-multi-inher) + (knr-argdecl-intro . 0) + (label . -1000) + (statement . 0) + (statement-block-intro . +) + (statement-case-intro . +) + (statement-cont . +) + (substatement . +) + )) + (indent-tabs-mode . t) + (show-trailing-whitespace . t) + )))) + + (dir-locals-set-directory-class + (expand-file-name "~/src/linux-trees") + 'linux-kernel) + +Esto hará que emacs funcione mejor con el estilo de código del kernel para +C en archivos bajo ``~/src/linux-trees``. + +Pero incluso si no logra que emacs realice un formateo correcto, no todo +está perdido: use ``indent``. + +Ahora bien, de nuevo, la sangría de GNU tiene la misma configuración de +muerte cerebral que GNU emacs tiene, por lo que necesita darle algunas +opciones de línea de comando. Sin embargo, eso no es tan malo, porque +incluso los creadores de GNU indent reconocen la autoridad de K&R (la gente +de GNU no es mala, solo están gravemente equivocados en este asunto), por +lo que simplemente de a la sangría las opciones ``-kr -i8`` (significa +``K&R, guiones de 8 caracteres``), o use ``scripts/Lindent``, que indenta +con ese estilo. + +``indent`` tiene muchas opciones, y especialmente cuando se trata de +comentar reformateos, es posible que desee echar un vistazo a la página del +manual. Pero recuerde: ``indent`` no es la solución para una mala +programación. + +Tenga en cuenta que también puede usar la herramienta ``clang-format`` para +ayudarlo con estas reglas, para volver a formatear rápidamente partes de su +código automáticamente, y revisar archivos completos para detectar errores +de estilo del código, errores tipográficos y posibles mejoras. También es +útil para ordenar ``#includes``, para alinear variables/macros, para +redistribuir texto y otras tareas similares. Vea el archivo +:ref:`Documentation/process/clang-format.rst <clangformat>` para más +detalles. + +10) Archivos de configuración de Kconfig +---------------------------------------- + +Para todos los archivos de configuración de Kconfig* en todo el árbol +fuente, la sangría es algo diferente. Las líneas bajo una definición +``config`` están indentadas con una tabulación, mientras que el texto de +ayuda tiene una sangría adicional de dos espacios. Ejemplo:: + + config AUDIT + bool "Soporte para auditar" + depends on NET + help + Habilita la infraestructura de auditoría que se puede usar con otro + subsistema kernel, como SELinux (que requiere esto para + registro de salida de mensajes avc). No hace auditoría de llamadas al + sistema sin CONFIG_AUDITSYSCALL. + +Características seriamente peligrosas (como soporte de escritura para +ciertos filesystems) deben anunciar esto de forma destacada en su cadena de +solicitud:: + + config ADFS_FS_RW + bool "ADFS write support (DANGEROUS)" + depends on ADFS_FS + ... + +Para obtener la documentación completa sobre los archivos de configuración, +consulte el archivo Documentation/kbuild/kconfig-language.rst. + + +11) Estructuras de datos +------------------------ + +Las estructuras de datos que tienen visibilidad fuera del contexto de un +solo subproceso en el que son creadas y destruidas, siempre debe tener +contadores de referencia. En el kernel, la recolección de basura no existe +(y fuera, la recolección de basura del kernel es lenta e ineficiente), lo +que significa que absolutamente **tiene** para hacer referencia y contar +todos sus usos. + +El conteo de referencias significa que puede evitar el bloqueo y permite +que múltiples usuarios tengan acceso a la estructura de datos en paralelo - +y no tengan que preocuparse de que la estructura, de repente, desaparezca +debajo de su control, solo porque durmieron o hicieron otra cosa por un +tiempo. + +Tenga en cuenta que el bloqueo **no** reemplaza el recuento de referencia. +El bloqueo se utiliza para mantener la coherencia de las estructuras de +datos, mientras que la referencia y contar es una técnica de gestión de +memoria. Por lo general, ambos son necesarios, y no deben confundirse entre +sí. + +De hecho, muchas estructuras de datos pueden tener dos niveles de conteo de +referencias, cuando hay usuarios de diferentes ``clases``. El conteo de +subclases cuenta el número de usuarios de la subclase y disminuye el conteo +global solo una vez, cuando el recuento de subclases llega a cero. + +Se pueden encontrar ejemplos de este tipo de ``recuento de referencias de +niveles múltiples`` en la gestión de memoria (``struct mm_struct``: +mm_users y mm_count), y en código del sistema de archivos +(``struct super_block``: s_count y s_active). + +Recuerde: si otro hilo puede encontrar su estructura de datos y usted no +tiene un recuento de referencias, es casi seguro que tiene un error. + +12) Macros, Enums y RTL +------------------------ + +Los nombres de macros que definen constantes y etiquetas en enumeraciones +(enums) están en mayúsculas. + +.. code-block:: c + + #define CONSTANTE 0x12345 + +Se prefieren los enums cuando se definen varias constantes relacionadas. + +Se aprecian los nombres de macro en MAYÚSCULAS, pero las macros que se +asemejan a funciones puede ser nombradas en minúscula. + +Generalmente, las funciones en línea son preferibles a las macros que se +asemejan a funciones. + +Las macros con varias instrucciones deben contenerse en un bloque do-while: + +.. code-block:: c + + #define macrofun(a, b, c) \ + do { \ + if (a == 5) \ + haz_esto(b, c); \ + } while (0) + +Cosas a evitar al usar macros: + +1) macros que afectan el flujo de control: + +.. code-block:: c + + #define FOO(x) \ + do { \ + if (blah(x) < 0) \ + return -EBUGGERED; \ + } while (0) + +es una **muy** mala idea. Parece una llamada de función pero sale de la +función de ``llamada``; no rompa los analizadores internos de aquellos que +leerán el código. + +2) macros que dependen de tener una variable local con un nombre mágico: + +.. code-block:: c + + #define FOO(val) bar(index, val) + +puede parecer algo bueno, pero es confuso como el infierno cuando uno lee +el código, y es propenso a romperse por cambios aparentemente inocentes. + +3) macros con argumentos que se usan como valores l: FOO(x) = y; le van +a morder si alguien, por ejemplo, convierte FOO en una función en línea. + +4) olvidarse de la precedencia: las macros que definen constantes usando +expresiones deben encerrar la expresión entre paréntesis. Tenga cuidado con +problemas similares con macros usando parámetros. + +.. code-block:: c + + #define CONSTANTE 0x4000 + #define CONSTEXP (CONSTANTE | 3) + +5) colisiones de espacio de nombres ("namespace") al definir variables +locales en macros que se asemejan a funciones: + +.. code-block:: c + + #define FOO(x) \ + ({ \ + typeof(x) ret; \ + ret = calc_ret(x); \ + (ret); \ + }) + +ret es un nombre común para una variable local -es menos probable que +__foo_ret colisione (coincida) con una variable existente. + +El manual de cpp trata las macros de forma exhaustiva. El manual interno de +gcc también cubre RTL, que se usa frecuentemente con lenguaje ensamblador +en el kernel. + +13) Imprimir mensajes del kernel +-------------------------------- + +A los desarrolladores del kernel les gusta ser vistos como alfabetizados. +Cuide la ortografía de los mensajes del kernel para causar una buena +impresión. No utilice contracciones incorrectas como ``dont``; use +``do not`` o ``don't`` en su lugar. Haga sus mensajes concisos, claros e +inequívocos. + +Los mensajes del kernel no tienen que terminar con un punto. + +Imprimir números entre paréntesis (%d) no agrega valor y debe evitarse. + +Hay varias modelos de macros de diagnóstico de driver en <linux/dev_printk.h> +que debe usar para asegurarse de que los mensajes coincidan con el +dispositivo correcto y driver, y están etiquetados con el nivel correcto: +dev_err(), dev_warn(), dev_info(), y así sucesivamente. Para mensajes que +no están asociados con un dispositivo particular, <linux/printk.h> define +pr_notice(), pr_info(), pr_warn(), pr_err(), etc. + +Crear buenos mensajes de depuración puede ser todo un desafío; y una vez +los tiene, pueden ser de gran ayuda para la resolución remota de problemas. +Sin embargo, la impresión de mensajes de depuración se maneja de manera +diferente a la impresión de otros mensajes que no son de depuración. +Mientras que las otras funciones pr_XXX() se imprimen incondicionalmente, +pr_debug() no lo hace; se compila fuera por defecto, a menos que DEBUG sea +definido o se establezca CONFIG_DYNAMIC_DEBUG. Eso es cierto para dev_dbg() +también, y una convención relacionada usa VERBOSE_DEBUG para agregar +mensajes dev_vdbg() a los ya habilitados por DEBUG. + +Muchos subsistemas tienen opciones de depuración de Kconfig para activar +-DDEBUG en el Makefile correspondiente; en otros casos, los archivos +usan #define DEBUG. Y cuando un mensaje de depuración debe imprimirse +incondicionalmente, por ejemplo si es ya dentro de una sección #ifdef +relacionada con la depuración, printk(KERN_DEBUG ...) puede ser usado. + +14) Reservando memoria +---------------------- + +El kernel proporciona los siguientes asignadores de memoria de propósito +general: kmalloc(), kzalloc(), kmalloc_array(), kcalloc(), vmalloc() y +vzalloc(). Consulte la documentación de la API para obtener más información. +a cerca de ellos. :ref:`Documentation/core-api/memory-allocation.rst +<memory_allocation>` + +La forma preferida para pasar el tamaño de una estructura es la siguiente: + +.. code-block:: c + + p = kmalloc(sizeof(*p), ...); + +La forma alternativa donde se deletrea el nombre de la estructura perjudica +la legibilidad, y presenta una oportunidad para un error cuando se cambia +el tipo de variable de puntero, pero el tamaño correspondiente de eso que +se pasa a un asignador de memoria no. + +Convertir el valor devuelto, que es un puntero vacío, es redundante. La +conversión desde el puntero vacío a cualquier otro tipo de puntero está +garantizado por la programación en idioma C. + +La forma preferida para asignar una matriz es la siguiente: + +.. code-block:: c + + p = kmalloc_array(n, sizeof(...), ...); + +La forma preferida para asignar una matriz a cero es la siguiente: + +.. code-block:: c + + p = kcalloc(n, sizeof(...), ...); + +Ambos casos verifican el desbordamiento en el tamaño de asignación n * +sizeof (...), y devuelven NULL si esto ocurrió. + +Todas estas funciones de asignación genéricas emiten un volcado de pila +(" stack dump") en caso de fallo cuando se usan sin __GFP_NOWARN, por lo +que no sirve de nada emitir un mensaje de fallo adicional cuando se +devuelva NULL. + +15) La enfermedad de inline +---------------------------- + +Parece haber una común percepción errónea de que gcc tiene una magica +opción "hazme más rápido" de aceleración, llamada ``inline`` (en línea). +Mientras que el uso de inlines puede ser apropiado (por ejemplo, como un +medio para reemplazar macros, consulte el Capítulo 12), muy a menudo no lo +es. El uso abundante de la palabra clave inline conduce a una mayor kernel, +que a su vez ralentiza el sistema en su conjunto, debido a una mayor huella +de icache para la CPU, y sencillamente porque hay menos memoria disponible +para el pagecache. Solo piense en esto; un fallo en la memoria caché de la +página provoca una búsqueda de disco, que tarda fácilmente 5 milisegundos. +Hay MUCHOS ciclos de CPU que puede entrar en estos 5 milisegundos. + +Una razonable regla general es no poner funciones inline que tengan más de +3 líneas de código en ellas. Una excepción a esta regla son los casos en +que se sabe que un parámetro es una constante en tiempo de compilación, y +como resultado de esto, usted *sabe*, el compilador podrá optimizar la +mayor parte de su función en tiempo de compilación. Para un buen ejemplo de +este último caso, véase la función en línea kmalloc(). + +A menudo, la gente argumenta que agregar funciones en línea que son +estáticas y se usan solo una vez, es siempre una victoria ya que no hay +perdida de espacio. Mientras esto es técnicamente correcto, gcc es capaz de +incorporarlos automáticamente sin ayuda, y esta el problema de +mantenimiento de eliminar el inline, cuando un segundo usuario supera el +valor potencial de la pista que le dice a gcc que haga algo que habría +hecho de todos modos. + +16) Valores devueltos por función y sus nombres +----------------------------------------------- + +Las funciones pueden devolver valores de muchos tipos diferentes, y uno de +lo más común es un valor que indica si la función tuvo éxito o ha fallado. +Dicho valor se puede representar como un número entero de código de error +(-Exxx = falla, 0 = éxito) o un booleano ``con éxito`` (0 = falla, distinto +de cero = éxito). + +La mezcla de estos dos tipos de representaciones es una fuente fértil de +errores difíciles de encontrar. Si el lenguaje C incluyera una fuerte +distinción entre enteros y booleanos, el compilador encontraría estos +errores por nosotros... pero no lo hace. Para ayudar a prevenir tales +errores, siga siempre esta convención:: + + Si el nombre de una función es una acción o un comando imperativo, + la función debe devolver un número entero de código de error. si el nombre + es un predicado, la función debe devolver un valor booleano "exitoso". + +Por ejemplo, ``agregar trabajo`` es un comando, y la función +agregar_trabajo() devuelve 0 en caso de éxito o -EBUSY en caso de fracaso. +De la misma manera, ``dispositivo PCI presente`` es un predicado, y la +función pci_dev_present() devuelve 1 si tiene éxito en encontrar un +dispositivo coincidente o 0 si no es así. + +Todas las funciones EXPORTed (exportadas) deben respetar esta convención, +al igual que todas las funciones publicas. Las funciones privadas +(estáticas) no lo necesitan, pero es recomendado que lo hagan. + +Las funciones cuyo valor devuelto es el resultado real de un cálculo, en +lugar de una indicación de si el cómputo tuvo éxito, no están sujetas a +esta regla. Generalmente indican fallo al devolver valores fuera del rango +de resultados. Los ejemplos típicos serían funciones que devuelven +punteros; estos usan NULL o el mecanismo ERR_PTR para informar de fallos. + +17) Usando bool +---------------- + +El tipo bool del kernel Linux es un alias para el tipo C99 _Bool. Los +valores booleanos pueden solo evaluar a 0 o 1, y la conversión implícita o +explícita a bool convierte automáticamente el valor en verdadero o falso. +Cuando se utilizan tipos booleanos, +!! no se necesita construcción, lo que elimina una clase de errores. + +Cuando se trabaja con valores booleanos, se deben usar las definiciones +verdadera y falsa, en lugar de 1 y 0. + +Los tipos de devolución de función bool y las variables de pila siempre +se pueden usar cuando esto sea adecuado. Se recomienda el uso de bool para +mejorar la legibilidad y, a menudo, es una mejor opción que 'int' para +almacenar valores booleanos. + +No use bool si el diseño de la línea de caché o el tamaño del valor son +importantes, ya que su tamaño y la alineación varía según la arquitectura +compilada. Las estructuras que son optimizadas para la alineación y el +tamaño no debe usar bool. + +Si una estructura tiene muchos valores verdadero/falso, considere +consolidarlos en un bitfield con miembros de 1 bit, o usando un tipo de +ancho fijo apropiado, como u8. + +De manera similar, para los argumentos de función, se pueden consolidar +muchos valores verdaderos/falsos en un solo argumento bit a bit 'flags' y +'flags' a menudo, puede ser una alternativa de argumento más legible si los +sitios de llamada tienen constantes desnudas de tipo verdaderas/falsas. + +De lo contrario, el uso limitado de bool en estructuras y argumentos puede +mejorar la legibilidad. + +18) No reinvente las macros del kernel +--------------------------------------- + +El archivo de cabecera include/linux/kernel.h contiene una serie de macros +que debe usar, en lugar de programar explícitamente alguna variante de +estos por usted mismo. Por ejemplo, si necesita calcular la longitud de una +matriz, aproveche la macro + +.. code-block:: c + + #define ARRAY_SIZE(x) (sizeof(x) / sizeof((x)[0])) + +De manera similar, si necesita calcular el tamaño de algún miembro de la +estructura, use + +.. code-block:: c + + #define sizeof_field(t, f) (sizeof(((t*)0)->f)) + +También hay macros min() y max() que realizan una verificación estricta de +tipos si lo necesita. Siéntase libre de leer detenidamente ese archivo de +encabezado para ver qué más ya está definido y que no debe reproducir en su +código. + +19) Editores modeline y otros desastres +--------------------------------------- + +Algunos editores pueden interpretar la información de configuración +incrustada en los archivos fuente, indicado con marcadores especiales. Por +ejemplo, emacs interpreta las líneas marcadas como esto: + +.. code-block:: c + + -*- mode: c -*- + +O así: + +.. code-block:: c + + /* + Local Variables: + compile-command: "gcc -DMAGIC_DEBUG_FLAG foo.c" + End: + */ + +Vim interpreta los marcadores que se ven así: + +.. code-block:: c + + /* vim:set sw=8 noet */ + +No incluya ninguno de estos en los archivos fuente. La gente tiene sus +propias configuraciones del editor, y sus archivos de origen no deben +anularlos. Esto incluye marcadores para sangría y configuración de modo. +La gente puede usar su propio modo personalizado, o puede tener algún otro +método mágico para que la sangría funcione correctamente. + + +20) Ensamblador inline +----------------------- + +En el código específico de arquitectura, es posible que deba usar +ensamblador en línea para interactuar con funcionalidades de CPU o +plataforma. No dude en hacerlo cuando sea necesario. Sin embargo, no use +ensamblador en línea de forma gratuita cuando C puede hacer el trabajo. +Puede y debe empujar el hardware desde C cuando sea posible. + +Considere escribir funciones auxiliares simples que envuelvan bits comunes +de ensamblador, en lugar de escribirlos repetidamente con ligeras +variaciones. Recuerde que el ensamblador en línea puede usar parámetros C. + +Las funciones de ensamblador grandes y no triviales deben ir en archivos .S, +con su correspondientes prototipos de C definidos en archivos de encabezado +en C. Los prototipos de C para el ensamblador deben usar ``asmlinkage``. + +Es posible que deba marcar su declaración asm como volátil, para evitar que +GCC la elimine si GCC no nota ningún efecto secundario. No siempre es +necesario hacerlo, sin embargo, y hacerlo innecesariamente puede limitar la +optimización. + +Al escribir una sola declaración de ensamblador en línea que contiene +múltiples instrucciones, ponga cada instrucción en una línea separada en +una string separada, y termine cada string excepto la última con ``\n\t`` +para indentar correctamente la siguiente instrucción en la salida en +ensamblador: + +.. code-block:: c + + asm ("magic %reg1, #42\n\t" + "more_magic %reg2, %reg3" + : /* outputs */ : /* inputs */ : /* clobbers */); + +21) Compilación condicional +--------------------------- + +Siempre que sea posible, no use condicionales de preprocesador (#if, +#ifdef) en archivos .c; de lo contrario, el código es más difícil de leer y +la lógica más difícil de seguir. En cambio, use dichos condicionales en un +archivo de encabezado que defina funciones para usar en esos archivos .c, +proporcionando versiones de código auxiliar sin operación en el caso #else, +y luego llame a estas funciones incondicionalmente desde archivos .c. El +compilador evitará generar cualquier código para las llamadas restantes, +produciendo resultados idénticos, pero la lógica es fácil de seguir. + +Prefiera compilar funciones completas, en lugar de porciones de funciones o +porciones de expresiones. En lugar de poner un ifdef en una expresión, +divida la totalidad de la expresión con una función de ayuda independiente +y aplique el condicional a esa función. + +Si tiene una función o variable que puede potencialmente quedar sin usar en +una configuración en particular, y el compilador advertiría sobre su +definición sin usar, marque la definición como __maybe_unused en lugar de +envolverla en un preprocesador condicional. (Sin embargo, si una función o +variable *siempre* acaba sin ser usada, bórrela.) + +Dentro del código, cuando sea posible, use la macro IS_ENABLED para +convertir un símbolo Kconfig en una expresión booleana de C, y utilícelo en +un condicional de C normal: + +.. code-block:: c + + if (IS_ENABLED(CONFIG_SOMETHING)) { + ... + } + +El compilador "doblará"" constantemente el condicional e incluirá o +excluirá el bloque de código al igual que con un #ifdef, por lo que esto no +agregará ningún tiempo de gastos generales en ejecución. Sin embargo, este +enfoque todavía permite que el compilador de C vea el código dentro del +bloque, y verifique que sea correcto (sintaxis, tipos, símbolo, referencias, +etc.). Por lo tanto, aún debe usar un #ifdef si el código dentro del bloque +hace referencia a símbolos que no existirán si no se cumple la condición. + +Al final de cualquier bloque #if o #ifdef no trivial (más de unas pocas +líneas), incluya un comentario después de #endif en la misma línea, +anotando la expresión condicional utilizada. Por ejemplo: + +.. code-block:: c + + #ifdef CONFIG_SOMETHING + ... + #endif /* CONFIG_SOMETHING */ + +22) No rompa el kernel +----------------------- + +En general, la decisión de romper el kernel pertenece al usuario, más que +al desarrollador del kernel. + +Evite el panic() +**************** + +panic() debe usarse con cuidado y principalmente solo durante el arranque +del sistema. panic() es, por ejemplo, aceptable cuando se queda sin memoria +durante el arranque y no puede continuar. + +Use WARN() en lugar de BUG() +**************************** + +No agregue código nuevo que use cualquiera de las variantes BUG(), como +BUG(), BUG_ON() o VM_BUG_ON(). En su lugar, use una variante WARN*(), +preferiblemente WARN_ON_ONCE(), y posiblemente con código de recuperación. +El código de recuperación no es requerido si no hay una forma razonable de +recuperar, al menos parcialmente. + +"Soy demasiado perezoso para tener en cuenta los errores" no es una excusa +para usar BUG(). Importantes corrupciones internas sin forma de continuar +aún pueden usar BUG(), pero necesitan una buena justificación. + +Use WARN_ON_ONCE() en lugar de WARN() o WARN_ON() +************************************************* + +Generalmente, se prefiere WARN_ON_ONCE() a WARN() o WARN_ON(), porque es +común que una condición de advertencia dada, si ocurre, ocurra varias +veces. Esto puede llenar el registro del kernel, e incluso puede ralentizar +el sistema lo suficiente como para que el registro excesivo se convierta en +su propio, adicional problema. + +No haga WARN a la ligera +************************ + +WARN*() está diseñado para situaciones inesperadas que nunca deberían +suceder. Las macros WARN*() no deben usarse para nada que se espera que +suceda durante un funcionamiento normal. No hay "checkeos" previos o +posteriores a la condición, por ejemplo. De nuevo: WARN*() no debe usarse +para una condición esperada que vaya a activarse fácilmente, por ejemplo, +mediante acciones en el espacio del usuario. pr_warn_once() es una +alternativa posible, si necesita notificar al usuario de un problema. + +No se preocupe sobre panic_on_warn de usuarios +********************************************** + +Algunas palabras más sobre panic_on_warn: Recuerde que ``panic_on_warn`` es +una opción disponible del kernel, y que muchos usuarios configuran esta +opción. Esta es la razón por la que hay un artículo de "No haga WARN a la +ligera", arriba. Sin embargo, la existencia de panic_on_warn de usuarios no +es una razón válida para evitar el uso juicioso de WARN*(). Esto se debe a +que quien habilita panic_on_warn, explícitamente pidió al kernel que +fallara si se dispara un WARN*(), y tales usuarios deben estar preparados +para afrontar las consecuencias de un sistema que es algo más probable que +se rompa. + +Use BUILD_BUG_ON() para aserciones en tiempo de compilación +*********************************************************** + +El uso de BUILD_BUG_ON() es aceptable y recomendado, porque es una aserción +en tiempo de compilación, que no tiene efecto en tiempo de ejecución. + +Apéndice I) Referencias +----------------------- + +The C Programming Language, Segunda edicion +por Brian W. Kernighan and Dennis M. Ritchie. +Prentice Hall, Inc., 1988. +ISBN 0-13-110362-8 (paperback), 0-13-110370-9 (hardback). + +The Practice of Programming +por Brian W. Kernighan and Rob Pike. +Addison-Wesley, Inc., 1999. +ISBN 0-201-61586-X. + +manuales GCC - en cumplimiento con K&R y este texto - para cpp, gcc, +detalles de gcc y sangría, todo disponible en https://www.gnu.org/manual/ + +WG14 es el grupo de trabajo de estandarización internacional de la +programación en lenguaje C, URL: http://www.open-std.org/JTC1/SC22/WG14/ + +:ref:`process/coding-style.rst <codingstyle>` del kernel, por greg@kroah.com at OLS 2002: +http://www.kroah.com/linux/talks/ols_2002_kernel_codingstyle_talk/html/ diff --git a/Documentation/translations/sp_SP/process/contribution-maturity-model.rst b/Documentation/translations/sp_SP/process/contribution-maturity-model.rst new file mode 100644 index 000000000..cc052ae81 --- /dev/null +++ b/Documentation/translations/sp_SP/process/contribution-maturity-model.rst @@ -0,0 +1,120 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../disclaimer-sp.rst + +:Original: Documentation/process/contribution-maturity-model.rst +:Translator: Avadhut Naik <avadhut.naik@amd.com> + +==================================================== +Modelo de Madurez de Contribución al Kernel de Linux +==================================================== + + +Los Antecedentes +================ + +Como parte de la cumbre de mantenedores del kernel de Linux 2021, hubo +una `discusión <https://lwn.net/Articles/870581/>`_ sobre los desafíos +en el reclutamiento de mantenedores del kernel, así como la sucesión de +los mantenedores. Algunas de las conclusiones de esa discusión incluyeron +que las empresas que forman parte de la comunidad del kernel de Linux +necesitan permitir que los ingenieros sean mantenedores como parte de su +trabajo, para que puedan convertirse en lideres respetados y finalmente, +en mantenedores del kernel. Para apoyar una fuente solida de talento, se +debe permitir y alentar a los desarrolladores a asumir contribuciones +upstream, como revisar los parches de otras personas, reestructurar la +infraestructura del kernel y escribir documentación. + +Con ese fin, Technical Advisory Board (TAB) de la Fundación Linux propone +este Modelo de Madurez de Contribución al Kernel de Linux. Estas +expectativas comunes para la participación con la comunidad upstream +tienen como objetivo aumentar la influencia de los desarrolladores +individuales, aumentar la colaboración de las organizaciones y mejorar +la salud general del ecosistema del kernel de Linux. + +El TAB insta a las organizaciones a evaluar continuamente su modelo de +madurez de Código Abierto y comprometerse a realizar mejoras para +alinearse con este modelo. Para ser eficaz, esta evaluación debe +incorporar la reacción de toda la organización, incluyendo la gerencia +y los desarrolladores en todos los niveles de antigüedad. En el espíritu +de Código Abierto, alentamos a las organizaciones a publicar sus +evaluaciones y planes para mejorar su participación con la comunidad +upstream. + +Nivel 0 +======= + +* A los ingenieros de software no se les permite contribuir con parches + al kernel de Linux. + +Nivel 1 +======= + +* A los ingenieros de software se les permite contribuir con parches al + kernel de Linux, ya sea como parte de sus responsabilidades de trabajo + o en su propio tiempo. + +Nivel 2 +======= + +* Se espera que los ingenieros de software contribuyan al kernel de Linux + como parte de sus responsabilidades de trabajo. +* Se proporcionará apoyo a los ingenieros de software para asistir a + conferencias relacionadas con Linux como parte de su trabajo. +* Las contribuciones de código upstream de un ingeniero de software se + considerarán en la promoción y las revisiones de rendimiento. + +Nivel 3 +======= + +* Se espera que los ingenieros de software revisen los parches (incluidos + los parches escritos por ingenieros de otras empresas) como parte de + sus responsabilidades de trabajo. +* Contribuir con presentaciones o ponencias a conferencias relacionadas + con Linux o académicas (como las organizadas por la Fundación Linux, + Usenix, ACM, etc.), se consideran parte del trabajo de un ingeniero. +* Las contribuciones a la comunidad de un ingeniero de software se + considerarán en la promoción y las revisiones de rendimiento. +* Las organizaciones informarán regularmente sobre las métricas de sus + contribuciones de código abierto y harán un seguimiento de estas + métricas a lo largo del tiempo. Estas métricas pueden publicarse + solo internamente dentro de la organización, o a discreción de la + organización, algunas o todas pueden publicarse externamente. Las + métricas que se sugieren encarecidamente incluyen: + + * El número de contribuciones al kernel upstream por equipo u + organización (por ejemplo, todas las personas que reportan a un + gerente o director o vicepresidente). + * El porcentaje de desarrolladores del kernel que han realizado + contribuciones upstream relativo al total de desarrolladores + del kernel en la organización. + * El intervalo de tiempo entre los kernels utilizados en los servidores + y/o productos de la organización y la fecha de publicación del kernel + upstream en el que se basa el kernel interno. + * El número de commits fuera del árbol de desarrollo presentes en los + kernels internos. + +Nivel 4 +======= + +* Se anima a los ingenieros de software a pasar una parte de su tiempo de + trabajo centrado en el Trabajo Ascendente, que se define como revisar + parches, servir en los comités de programas, mejorar la infraestructura + del proyecto central como escribir o mantener pruebas, reducir la deuda + de tecnología upstream, escribir documentación, etc. +* Los ingenieros de software son apoyados para ayudar a organizar + conferencias relacionadas con Linux. +* Las organizaciones considerarán los comentarios de los miembros de la + comunidad en las revisiones oficiales de rendimiento. + +Nivel 5 +======= + +* El desarrollo del kernel upstream se considera un puesto de trabajo + formal, con al menos un tercio del tiempo del ingeniero pasado a hacer + el Trabajo Ascendente. +* Las organizaciones buscarán activamente las reacciones de los miembros + de la comunidad como un factor en las revisiones oficiales de + rendimiento. +* Las organizaciones informarán regularmente internamente sobre la ratio + de trabajo upstream a trabajo enfocado en perseguir directamente los + objetivos comerciales. diff --git a/Documentation/translations/sp_SP/process/deprecated.rst b/Documentation/translations/sp_SP/process/deprecated.rst new file mode 100644 index 000000000..d52120e0d --- /dev/null +++ b/Documentation/translations/sp_SP/process/deprecated.rst @@ -0,0 +1,381 @@ +.. include:: ../disclaimer-sp.rst + +:Original: :ref:`Documentation/process/deprecated.rst <deprecated>` +:Translator: Sergio Gonzalez <sergio.collado@gmail.com> + +.. _sp_deprecated: + +============================================================================ +Interfaces obsoletos, Características del lenguaje, Atributos y Convenciones +============================================================================ + +En un mundo perfecto, sería posible convertir todas las instancias de +alguna API obsoleta en una nueva API y quitar la API anterior en un +único ciclo de desarrollo. Desafortunadamente, debido al tamaño del kernel, +la jerarquía de mantenimiento, y el tiempo, no siempre es posible hacer +estos cambios de una única vez. Esto significa que las nuevas instancias +han de ir creándose en el kernel, mientras que las antiguas se quitan, +haciendo que la cantidad de trabajo para limpiar las APIs crezca. Para +informar a los desarrolladores sobre qué ha sido declarado obsoleto y por +qué, ha sido creada esta lista como un lugar donde indicar cuando los usos +obsoletos son propuestos para incluir en el kernel. + +__deprecated +------------ +Mientras que este atributo señala visualmente que un interface ha sido +declarado obsoleto, este `no produce más avisos durante las compilaciones +<https://git.kernel.org/linus/771c035372a036f83353eef46dbb829780330234>`_ +porque uno de los objetivos del kernel es que compile sin avisos, y +nadie ha hecho nada para quitar estos interfaces obsoletos. Mientras +que usar `__deprecated` es sencillo para anotar una API obsoleta en +un archivo de cabecera, no es la solución completa. Dichos interfaces +deben o bien ser quitados por completo, o añadidos a este archivo para +desanimar a otros a usarla en el futuro. + +BUG() y BUG_ON() +---------------- +Use WARN() y WARN_ON() en su lugar, y gestione las condiciones de error +"imposibles" tan elegantemente como se pueda. Mientras que la familia de +funciones BUG() fueron originalmente diseñadas para actuar como una +"situación imposible", confirmar y disponer de un hilo del kernel de forma +"segura", estas funciones han resultado ser demasiado arriesgadas. (e.g. +"¿en qué orden se necesitan liberar los locks? ¿Se han restaurado sus +estados?). La popular función BUG() desestabilizará el sistema o lo romperá +totalmente, lo cual hace imposible depurarlo o incluso generar reportes de +crash. Linus tiene una `opinión muy fuerte +<https://lore.kernel.org/lkml/CA+55aFy6jNLsywVYdGp83AMrXBo_P-pkjkphPGrO=82SPKCpLQ@mail.gmail.com/>`_ +y sentimientos `sobre esto +<https://lore.kernel.org/lkml/CAHk-=whDHsbK3HTOpTF=ue_o04onRwTEaK_ZoJp_fjbqq4+=Jw@mail.gmail.com/>`_. + +Nótese que la familia de funciones WARN() únicamente debería ser usada +en situaciones que se "esperan no sean alcanzables". Si se quiere +avisar sobre situaciones "alcanzables pero no deseadas", úsese la familia +de funciones pr_warn(). Los responsables del sistema pueden haber definido +*panic_on_warn* sysctl para asegurarse que sus sistemas no continúan +ejecutándose en presencia del condiciones "no alcanzables". (Por ejemplo, +véase commits como `este +<https://git.kernel.org/linus/d4689846881d160a4d12a514e991a740bcb5d65a>`_.) + +Operaciones aritméticas en los argumentos de reserva de memoria +--------------------------------------------------------------- +Los cálculos dinámicos de tamaño (especialmente multiplicaciones) no +deberían realizarse en los argumentos de reserva de memoria (o similares) +debido al riesgo de desbordamiento. Esto puede llevar a valores rotando y +que se realicen reservas de memoria menores que las que se esperaban. El +uso de esas reservas puede llevar a desbordamientos en el 'heap' de memoria +y otros funcionamientos incorrectos. (Una excepción a esto son los valores +literales donde el compilador si puede avisar si estos puede desbordarse. +De todos modos, el método recomendado en estos caso es reescribir el código +como se sugiere a continuación para evitar las operaciones aritméticas en +la reserva de memoria.) + +Por ejemplo, no utilice `count * size`` como argumento, como en:: + + foo = kmalloc(count * size, GFP_KERNEL); + +En vez de eso, utilice la reserva con dos argumentos:: + + foo = kmalloc_array(count, size, GFP_KERNEL); + +Específicamente, kmalloc() puede ser sustituido con kmalloc_array(), +kzalloc() puede ser sustituido con kcalloc(). + +Si no existen funciones con dos argumentos, utilice las funciones que se +saturan, en caso de desbordamiento:: + + bar = vmalloc(array_size(count, size)); + +Otro caso común a evitar es calcular el tamaño de una estructura com +la suma de otras estructuras, como en:: + + header = kzalloc(sizeof(*header) + count * sizeof(*header->item), + GFP_KERNEL); + +En vez de eso emplee:: + + header = kzalloc(struct_size(header, item, count), GFP_KERNEL); + +.. note:: Si se usa struct_size() en una estructura que contiene un elemento + de longitud cero o un array de un único elemento como un array miembro, + por favor reescribir ese uso y cambiar a un `miembro array flexible + <#zero-length-and-one-element-arrays>`_ + + +Para otros cálculos, por favor use las funciones de ayuda: size_mul(), +size_add(), and size_sub(). Por ejemplo, en el caso de:: + + foo = krealloc(current_size + chunk_size * (count - 3), GFP_KERNEL); + +Re-escríbase, como:: + + foo = krealloc(size_add(current_size, + size_mul(chunk_size, + size_sub(count, 3))), GFP_KERNEL); + +Para más detalles, mire también array3_size() y flex_array_size(), +como también la familia de funciones relacionadas check_mul_overflow(), +check_add_overflow(), check_sub_overflow(), y check_shl_overflow(). + + +simple_strtol(), simple_strtoll(), simple_strtoul(), simple_strtoull() +---------------------------------------------------------------------- +Las funciones: simple_strtol(), simple_strtoll(), simple_strtoul(), y +simple_strtoull() explícitamente ignoran los desbordamientos, lo que puede +llevar a resultados inesperados por las funciones que las llaman. Las +funciones respectivas kstrtol(), kstrtoll(), kstrtoul(), y kstrtoull() +tienden a ser reemplazos correctos, aunque nótese que necesitarán que la +cadena de caracteres termine en NUL o en el carácter de línea nueva. + + +strcpy() +-------- +strcpy() no realiza verificaciones de los límites del buffer de destino. +Esto puede resultar en desbordamientos lineals más allá del fin del buffer, +causando todo tipo de errores. Mientras `CONFIG_FORTIFY_SOURCE=y` otras +varias opciones de compilación reducen el riesgo de usar esta función, no +hay ninguna buena razón para añadir nuevos usos de esta. El remplazo seguro +es la función strscpy(), aunque se ha de tener cuidado con cualquier caso +en el el valor retornado por strcpy() sea usado, ya que strscpy() no +devuelve un puntero a el destino, sino el número de caracteres no nulos +compilados (o el valor negativo de errno cuando se trunca la cadena de +caracteres). + +strncpy() en cadenas de caracteres terminadas en NUL +---------------------------------------------------- +El uso de strncpy() no garantiza que el buffer de destino esté terminado en +NUL. Esto puede causar varios errores de desbordamiento en lectura y otros +tipos de funcionamiento erróneo debido a que falta la terminación en NUL. +Esta función también termina la cadena de caracteres en NUL en el buffer de +destino si la cadena de origen es más corta que el buffer de destino, lo +cual puede ser una penalización innecesaria para funciones usen esta +función con cadenas de caracteres que sí están terminadas en NUL. + +Cuando se necesita que la cadena de destino sea terminada en NUL, +el mejor reemplazo es usar la función strscpy(), aunque se ha de tener +cuidado en los casos en los que el valor de strncpy() fuera usado, ya que +strscpy() no devuelve un puntero al destino, sino el número de +caracteres no nulos copiados (o el valor negativo de errno cuando se trunca +la cadena de caracteres). Cualquier caso restante que necesitase todavía +ser terminado en el caracter nulo, debería usar strscpy_pad(). + +Si una función usa cadenas de caracteres que no necesitan terminar en NUL, +debería usarse strtomem(), y el destino debería señalarse con el atributo +`__nonstring +<https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html>`_ +para evitar avisos futuros en el compilador. Para casos que todavía +necesitan cadenas de caracteres que se rellenen al final con el +caracter NUL, usar strtomem_pad(). + +strlcpy() +--------- +strlcpy() primero lee por completo el buffer de origen (ya que el valor +devuelto intenta ser el mismo que el de strlen()). Esta lectura puede +sobrepasar el límite de tamaño del destino. Esto ineficiente y puede causar +desbordamientos de lectura si la cadena de origen no está terminada en el +carácter NUL. El reemplazo seguro de esta función es strscpy(), pero se ha +de tener cuidado que en los casos en lso que se usase el valor devuelto de +strlcpy(), ya que strscpy() devolverá valores negativos de erno cuando se +produzcan truncados. + +Especificación de formato %p +---------------------------- +Tradicionalmente,el uso de "%p" en el formato de cadenas de caracteres +resultaría en exponer esas direcciones en dmesg, proc, sysfs, etc. En vez +de dejar que sean una vulnerabilidad, todos los "%p" que se usan en el +kernel se imprimen como un hash, haciéndolos efectivamente inutilizables +para usarlos como direcciones de memoria. Nuevos usos de "%p" no deberían +ser añadidos al kernel. Para textos de direcciones, usar "%pS" es +mejor, ya que resulta en el nombre del símbolo. Para prácticamente el +resto de casos, mejor no usar "%p" en absoluto. + +Parafraseando las actuales `direcciones de Linus <https://lore.kernel.org/lkml/CA+55aFwQEd_d40g4mUCSsVRZzrFPUJt74vc6PPpb675hYNXcKw@mail.gmail.com/>`_: + +- Si el valor "hasheado" "%p" no tienen ninguna finalidad, preguntarse si el + puntero es realmente importante. ¿Quizás se podría quitar totalmente? +- Si realmente se piensa que el valor del puntero es importante, ¿porqué + algún estado del sistema o nivel de privilegio de usuario es considerado + "especial"? Si piensa que puede justificarse (en comentarios y mensajes + del commit), de forma suficiente como para pasar el escrutinio de Linux, + quizás pueda usar el "%p", a la vez que se asegura que tiene los permisos + correspondientes. + +Si está depurando algo donde el "%p" hasheado está causando problemas, +se puede arrancar temporalmente con la opción de depuración "`no_hash_pointers +<https://git.kernel.org/linus/5ead723a20e0447bc7db33dc3070b420e5f80aa6>`_". + + +Arrays de longitud variable (VLAs) +---------------------------------- +Usando VLA en la pila (stack) produce un código mucho peor que los arrays +de tamaño estático. Mientras que estos errores no triviales de `rendimiento +<https://git.kernel.org/linus/02361bc77888>`_ son razón suficiente +para no usar VLAs, esto además son un riesgo de seguridad. El crecimiento +dinámico del array en la pila, puede exceder la memoria restante en +el segmento de la pila. Esto podría llevara a un fallo, posible sobre-escritura +de contenido al final de la pila (cuando se construye sin +`CONFIG_THREAD_INFO_IN_TASK=y`), o sobre-escritura de la memoria adyacente +a la pila (cuando se construye sin `CONFIG_VMAP_STACK=y`). + + +Switch case fall-through implícito +---------------------------------- +El lenguaje C permite a las sentencias 'switch' saltar de un caso al +siguiente caso cuando la sentencia de ruptura "break" no aparece al final +del caso. Esto, introduce ambigüedad en el código, ya que no siempre está +claro si el 'break' que falta es intencionado o un olvido. Por ejemplo, no +es obvio solamente mirando al código si `STATE_ONE` está escrito para +intencionadamente saltar en `STATE_TWO`:: + + switch (value) { + case STATE_ONE: + do_something(); + case STATE_TWO: + do_other(); + break; + default: + WARN("unknown state"); + } + +Ya que ha habido una larga lista de defectos `debidos a declaraciones de "break" +que faltan <https://cwe.mitre.org/data/definitions/484.html>`_, no se +permiten 'fall-through' implícitos. Para identificar 'fall-through' +intencionados, se ha adoptado la pseudo-palabra-clave macro "falltrhrough", +que expande las extensiones de gcc `__attribute__((__fallthrough__)) +<https://gcc.gnu.org/onlinedocs/gcc/Statement-Attributes.html>`_. +(Cuando la sintaxis de C17/c18 `[[fallthrough]]` sea más comúnmente +soportadas por los compiladores de C, analizadores estáticos, e IDEs, +se puede cambiar a usar esa sintaxis para esa pseudo-palabra-clave. + +Todos los bloques switch/case deben acabar en uno de: + +* break; +* fallthrough; +* continue; +* goto <label>; +* return [expression]; + + +Arrays de longitud cero y un elemento +------------------------------------- +Hay una necesidad habitual en el kernel de proveer una forma para declarar +un grupo de elementos consecutivos de tamaño dinámico en una estructura. +El código del kernel debería usar siempre `"miembros array flexible" <https://en.wikipedia.org/wiki/Flexible_array_member>`_ +en estos casos. El estilo anterior de arrays de un elemento o de longitud +cero, no deben usarse más. + +En el código C más antiguo, los elementos finales de tamaño dinámico se +obtenían especificando un array de un elemento al final de una estructura:: + + struct something { + size_t count; + struct foo items[1]; + }; + +En código C más antiguo, elementos seguidos de tamaño dinámico eran creados +especificando una array de un único elemento al final de una estructura:: + + struct something { + size_t count; + struct foo items[1]; + }; + +Esto llevó a resultados incorrectos en los cálculos de tamaño mediante +sizeof() (el cual hubiera necesitado eliminar el tamaño del último elemento +para tener un tamaño correcto de la "cabecera"). Una `extensión de GNU C +<https://gcc.gnu.org/onlinedocs/gcc/Zero-Length.html>`_ se empezó a usar +para permitir los arrays de longitud cero, para evitar estos tipos de +problemas de tamaño:: + + struct something { + size_t count; + struct foo items[0]; + }; + +Pero esto llevó a otros problemas, y no solucionó algunos otros problemas +compartidos por ambos estilos, como no ser capaz de detectar cuando ese array +accidentalmente _no_ es usado al final de la estructura (lo que podía pasar +directamente, o cuando dicha estructura era usada en uniones, estructuras +de estructuras, etc). + +C99 introdujo "los arrays miembros flexibles", los cuales carecen de un +tamaño numérico en su declaración del array:: + + struct something { + size_t count; + struct foo items[]; + }; + +Esta es la forma en la que el kernel espera que se declaren los elementos +de tamaño dinámico concatenados. Esto permite al compilador generar +errores, cuando el array flexible no es declarado en el último lugar de la +estructura, lo que ayuda a prevenir errores en él código del tipo +`comportamiento indefinido <https://git.kernel.org/linus/76497732932f15e7323dc805e8ea8dc11bb587cf>`_. +Esto también permite al compilador analizar correctamente los tamaños de +los arrays (via sizeof(), `CONFIG_FORTIFY_SOURCE`, y `CONFIG_UBSAN_BOUNDS`). +Por ejemplo, si no hay un mecanismo que avise que el siguiente uso de +sizeof() en un array de longitud cero, siempre resulta en cero:: + + struct something { + size_t count; + struct foo items[0]; + }; + + struct something *instance; + + instance = kmalloc(struct_size(instance, items, count), GFP_KERNEL); + instance->count = count; + + size = sizeof(instance->items) * instance->count; + memcpy(instance->items, source, size); + +En la última línea del código anterior, ``zero`` vale ``cero``, cuando uno +podría esperar que representa el tamaño total en bytes de la memoria dinámica +reservada para el array consecutivo ``items``. Aquí hay un par de ejemplos +más sobre este tema: `link 1 +<https://git.kernel.org/linus/f2cd32a443da694ac4e28fbf4ac6f9d5cc63a539>`_, +`link 2 +<https://git.kernel.org/linus/ab91c2a89f86be2898cee208d492816ec238b2cf>`_. +Sin embargo, los array de miembros flexibles tienen un type incompleto, y +no se ha de aplicar el operador sizeof()<https://gcc.gnu.org/onlinedocs/gcc/Zero-Length.html>`_, +así cualquier mal uso de dichos operadores será detectado inmediatamente en +el momento de compilación. + +Con respecto a los arrays de un único elemento, se ha de ser consciente de +que dichos arrays ocupan al menos tanto espacio como un único objeto del +tipo https://gcc.gnu.org/onlinedocs/gcc/Zero-Length.html>`_, de ahí que +estos contribuyan al tamaño de la estructura que los contiene. Esto es +proclive a errores cada vez que se quiere calcular el tamaño total de la +memoria dinámica para reservar una estructura que contenga un array de este +tipo como su miembro:: + + struct something { + size_t count; + struct foo items[1]; + }; + + struct something *instance; + + instance = kmalloc(struct_size(instance, items, count - 1), GFP_KERNEL); + instance->count = count; + + size = sizeof(instance->items) * instance->count; + memcpy(instance->items, source, size); + +En el ejemplo anterior, hemos de recordar calcular ``count - 1``, cuando se +usa la función de ayuda struct_size(), de otro modo estaríamos +--desintencionadamente--reservando memoria para un ``items`` de más. La +forma más clara y menos proclive a errores es implementar esto mediante el +uso de `array miembro flexible`, junto con las funciones de ayuda: +struct_size() y flex_array_size():: + + struct something { + size_t count; + struct foo items[]; + }; + + struct something *instance; + + instance = kmalloc(struct_size(instance, items, count), GFP_KERNEL); + instance->count = count; + + memcpy(instance->items, source, flex_array_size(instance, items, instance->count)); diff --git a/Documentation/translations/sp_SP/process/email-clients.rst b/Documentation/translations/sp_SP/process/email-clients.rst new file mode 100644 index 000000000..fdf1e51b8 --- /dev/null +++ b/Documentation/translations/sp_SP/process/email-clients.rst @@ -0,0 +1,374 @@ +.. include:: ../disclaimer-sp.rst + +:Original: :ref:`Documentation/process/email-clients.rst <email_clients>` +:Translator: Carlos Bilbao <carlos.bilbao@amd.com> + +.. _sp_email_clients: + +Información de clientes de correo electrónico para Linux +======================================================== + +Git +--- + +A día de hoy, la mayoría de los desarrolladores usan ``git send-email`` en +lugar de los clientes de correo electrónico normales. La página de manual +para esto es bastante buena. En la recepción del correo, los maintainers +usan ``git am`` para aplicar los parches. + +Si es usted nuevo en ``git`` entonces envíese su primer parche. Guárdelo +como texto sin formato, incluidos todos los encabezados. Ejecute ``git am raw_email.txt`` +y luego revise el registro de cambios con ``git log``. Cuando eso funcione, +envíe el parche a la(s) lista(s) de correo apropiada(s). + +Preferencias Generales +---------------------- + +Los parches para el kernel de Linux se envían por correo electrónico, +preferiblemente como texto en línea en el cuerpo del correo electrónico. +Algunos maintainers aceptan archivos adjuntos, pero entonces los archivos +adjuntos deben tener tipo de contenido ``text/plain``. Sin embargo, los +archivos adjuntos generalmente están mal vistos porque hacen que citar +partes del parche sea más difícil durante el proceso de revisión del +parche. + +También se recomienda encarecidamente que utilice texto sin formato en el +cuerpo del correo electrónico, para parches y otros correos electrónicos +por igual. https://useplaintext.email puede ser útil para obtener +información sobre cómo configurar su cliente de correo electrónico +preferido, así como una lista de clientes de correo electrónico +recomendados si aún no tiene una preferencia. + +Los clientes de correo electrónico que se utilizan para los parches del +kernel Linux deben enviar el texto del parche intacto. Por ejemplo, no +deben modificar ni eliminar pestañas o espacios, incluso al principio o al +final de las líneas. + +No envíe parches con ``format=flowed``. Esto puede causar saltos de línea +no deseados e inesperados. + +No deje que su cliente de correo electrónico ajuste automáticamente las +palabras por usted. Esto también puede corromper su parche. + +Los clientes de correo electrónico no deben modificar la codificación del +de caracteres del texto. Los parches enviados por correo electrónico deben +estar en codificación ASCII o UTF-8 únicamente. Si configura su cliente de +correo electrónico para enviar correos electrónicos con codificación UTF-8, +evite algunos posibles problemas con los caracteres. + +Los clientes de correo electrónico deben generar y mantener los +encabezados "References:" o "In-Reply-To:" para que el hilo de correo no +se rompa. + +Copiar y pegar (o cortar y pegar) generalmente no funciona para los +parches, porque las tabulaciones se convierten en espacios. Utilizar +xclipboard, xclip y/o xcutsel puede funcionar, pero es mejor probarlo usted +mismo o simplemente evitar copiar y pegar. + +No utilice firmas PGP/GPG en el correo que contiene parches. +Esto rompe muchos scripts que leen y aplican los parches. +(Esto debería ser reparable.) + +Es una buena idea enviarse un parche a sí mismo, guardar el mensaje +recibido, y aplicarlo con éxito con 'patch' antes de enviar el parche a las +listas de correo de Linux. + +Algunas sugerencias para el cliente de correo electrónico (MUA) +--------------------------------------------------------------- + +Aquí hay algunos consejos específicos de configuración de MUA para editar y +enviar parches para el kernel de Linux. Estos no pretenden cubrir todo +detalle de configuración de los paquetes de software. + +Leyenda: + +- TUI = text-based user interface (interfaz de usuario basada en texto) +- GUI = graphical user interface (interfaz de usuario gráfica) + +Alpine (TUI) +************ + +Opciones de configuración: + +En la sección :menuselection:`Sending Preferences`: + +- :menuselection: `Do Not Send Flowed Text` debe estar ``enabled`` +- :menuselection:`Strip Whitespace Before Sending` debe estar ``disabled`` + +Al redactar el mensaje, el cursor debe colocarse donde el parche debería +aparecer, y luego presionando :kbd:`CTRL-R` se le permite especificar e +archivo de parche a insertar en el mensaje. + +Claws Mail (GUI) +**************** + +Funciona. Algunos usan esto con éxito para los parches. + +Para insertar un parche haga :menuselection:`Message-->Insert File` (:kbd:`CTRL-I`) +o use un editor externo. + +Si el parche insertado debe editarse en la ventana de composición de Claws +"Auto wrapping" en +:menuselection:`Configuration-->Preferences-->Compose-->Wrapping` debe +permanecer deshabilitado. + +Evolution (GUI) +*************** + +Algunos usan esto con éxito para sus parches. + +Cuando escriba un correo seleccione: Preformat + desde :menuselection:`Format-->Paragraph Style-->Preformatted` (:kbd:`CTRL-7`) + o en la barra de herramientas + +Luego haga: +:menuselection:`Insert-->Text File...` (:kbd:`ALT-N x`) +para insertar el parche. + +También puede hacer ``diff -Nru old.c new.c | xclip``, seleccione +:menuselection:`Preformat`, luego pege con el boton del medio. + +Kmail (GUI) +*********** + +Algunos usan Kmail con éxito para los parches. + +La configuración predeterminada de no redactar en HTML es adecuada; no haga +cambios en esto. + +Al redactar un correo electrónico, en las opciones, desmarque "word wrap". +La única desventaja es que cualquier texto que escriba en el correo +electrónico no se ajustará a cada palabra, por lo que tendrá que ajustar +manualmente el texto antes del parche. La forma más fácil de evitar esto es +redactar su correo electrónico con Word Wrap habilitado, luego guardar +como borrador. Una vez que lo vuelva a sacar de sus borradores, estará +envuelto por palabras y puede desmarcar "word wrap" sin perder el existente +texto. + +En la parte inferior de su correo electrónico, coloque el delimitador de +parche de uso común antes de insertar su parche: tres guiones (``---``). + +Luego desde la opción de menu :menuselection:`Message` seleccione +:menuselection:`insert file` y busque su parche. +De forma adicional, puede personalizar el menú de la barra de herramientas +de creación de mensajes y poner el icono :menuselection:`insert file`. + +Haga que la ventana del editor sea lo suficientemente ancha para que no se +envuelva ninguna línea. A partir de KMail 1.13.5 (KDE 4.5.4), KMail +aplicará ajuste de texto al enviar el correo electrónico si las líneas se +ajustan en la ventana del redactor. Tener ajuste de palabras deshabilitado +en el menú Opciones no es suficiente. Por lo tanto, si su parche tiene +líneas muy largas, debe hacer que la ventana del redactor sea muy amplia +antes de enviar el correo electrónico. Consulte: https://bugs.kde.org/show_bug.cgi?id=174034 + +You can safely GPG sign attachments, but inlined text is preferred for +patches so do not GPG sign them. Signing patches that have been inserted +as inlined text will make them tricky to extract from their 7-bit encoding. + +Puede firmar archivos adjuntos con GPG de forma segura, pero se prefiere el +texto en línea para parches, así que no los firme con GPG. Firmar parches +que se han insertado como texto en línea hará que sea difícil extraerlos de +su codificación de 7 bits. + +Si es absolutamente necesario enviar parches como archivos adjuntos en +lugar de como texto en línea, haga clic con el botón derecho en el archivo +adjunto y seleccione :menuselection:`properties`, y luego +:menuselection:`Suggest automatic display` para hacer que el archivo +adjunto esté en línea para que sea más visible. + +Al guardar parches que se envían como texto en línea, seleccione el correo +electrónico que contiene el parche del panel de la lista de mensajes, haga +clic con el botón derecho y seleccione :menuselection:`save as`. Puede usar +todo el correo electrónico sin modificar como un parche de estar bien +compuesto. Los correos electrónicos se guardan como lectura y escritura +solo para el usuario, por lo que tendrá que cambiarlos para que sean +legibles en grupo y en todo el mundo si copia estos en otro lugar. + +Notas de Lotus (GUI) +******************** + +Huya de este. + +IBM Verse (Web GUI) +******************* + +Vea notas sobre Lotus. + +Mutt (TUI) +********** + +Muchos desarrolladores de Linux usan ``mutt``, por lo que debe funcionar +bastante bien. + +Mutt no viene con un editor, por lo que cualquier editor que use debe ser +utilizado de forma que no haya saltos de línea automáticos. La mayoría de +los editores tienen una opción :menuselection:`insert file` que inserta el +contenido de un archivo inalterado. + +Para usar ``vim`` con mutt:: + + set editor="vi" + +Si utiliza xclip, escriba el comando:: + + :set paste + +antes del boton del medio o shift-insert o use:: + + :r filename + +si desea incluir el parche en línea. +(a)ttach (adjuntar) funciona bien sin ``set paste``. + +También puedes generar parches con ``git format-patch`` y luego usar Mutt +para enviarlos:: + + $ mutt -H 0001-some-bug-fix.patch + +Opciones de configuración: + +Debería funcionar con la configuración predeterminada. +Sin embargo, es una buena idea establecer ``send_charset`` en: + + set send_charset="us-ascii:utf-8" + +Mutt es altamente personalizable. Aquí tiene una configuración mínima para +empezar a usar Mutt para enviar parches a través de Gmail:: + + # .muttrc + # ================ IMAP ==================== + set imap_user = 'suusuario@gmail.com' + set imap_pass = 'sucontraseña' + set spoolfile = imaps://imap.gmail.com/INBOX + set folder = imaps://imap.gmail.com/ + set record="imaps://imap.gmail.com/[Gmail]/Sent Mail" + set postponed="imaps://imap.gmail.com/[Gmail]/Drafts" + set mbox="imaps://imap.gmail.com/[Gmail]/All Mail" + + # ================ SMTP ==================== + set smtp_url = "smtp://username@smtp.gmail.com:587/" + set smtp_pass = $imap_pass + set ssl_force_tls = yes # Requerir conexión encriptada + + # ================ Composición ==================== + set editor = `echo \$EDITOR` + set edit_headers = yes # Ver los encabezados al editar + set charset = UTF-8 # valor de $LANG; also fallback for send_charset + # El remitente, la dirección de correo electrónico y la línea de firma deben coincidir + unset use_domain # Porque joe@localhost es simplemente vergonzoso + set realname = "SU NOMBRE" + set from = "username@gmail.com" + set use_from = yes + +Los documentos Mutt tienen mucha más información: + + https://gitlab.com/muttmua/mutt/-/wikis/UseCases/Gmail + + http://www.mutt.org/doc/manual/ + +Pine (TUI) +********** + +Pine ha tenido algunos problemas de truncamiento de espacios en blanco en +el pasado, pero estos todo debería estar arreglados ahora. + +Use alpine (sucesor de pino) si puede. + +Opciones de configuración: + +- ``quell-flowed-text`` necesitado para versiones actuales +- la opción ``no-strip-whitespace-before-send`` es necesaria + + +Sylpheed (GUI) +************** + +- Funciona bien para insertar texto (o usar archivos adjuntos). +- Permite el uso de un editor externo. +- Es lento en carpetas grandes. +- No realizará la autenticación TLS SMTP en una conexión que no sea SSL. +- Tiene una útil barra de reglas en la ventana de redacción. +- Agregar direcciones a la libreta de direcciones no las muestra + adecuadamente. + +Thunderbird (GUI) +***************** + +Thunderbird es un clon de Outlook al que le gusta alterar el texto, pero +hay formas para obligarlo a comportarse. + +Después de hacer las modificaciones, que incluye instalar las extensiones, +necesita reiniciar Thunderbird. + +- Permitir el uso de un editor externo: + + Lo más fácil de hacer con Thunderbird y los parches es usar extensiones + que abran su editor externo favorito. + + Aquí hay algunas extensiones de ejemplo que son capaces de hacer esto. + + - "External Editor Revived" + + https://github.com/Frederick888/external-editor-revived + + https://addons.thunderbird.net/en-GB/thunderbird/addon/external-editor-revived/ + + Requiere instalar un "native messaging host". + Por favor, lea la wiki que se puede encontrar aquí: + https://github.com/Frederick888/external-editor-revived/wiki + + - "External Editor" + + https://github.com/exteditor/exteditor + + Para hacer esto, descargue e instale la extensión, luego abra la ventana + :menuselection:`compose`, agregue un botón para ello usando + :menuselection:`View-->Toolbars-->Customize...` + luego simplemente haga clic en el botón nuevo cuando desee usar el editor + externo. + + Tenga en cuenta que "External Editor" requiere que su editor no haga + fork, o en otras palabras, el editor no debe regresar antes de cerrar. + Es posible que deba pasar flags adicionales o cambiar la configuración + de su editor. En particular, si está utilizando gvim, debe pasar la + opción -f a gvim poniendo ``/usr/bin/gvim --nofork"`` (si el binario + está en ``/usr/bin``) al campo del editor de texto en los ajustes + :menuselection:`external editor`. Si está utilizando algún otro editor, + lea su manual para saber cómo hacer esto. + +Para sacarle algo de sentido al editor interno, haga esto: + +- Edite sus ajustes de configuración de Thunderbird para que no utilice ``format=flowed``! + Vaya a su ventana principal y busque el botón de su menú desplegable principal. + :menuselection:`Main Menu-->Preferences-->General-->Config Editor...` + para abrir el editor de registro de Thunderbird. + + - Seleccione ``mailnews.send_plaintext_flowed`` como ``false`` + + - Seleccione ``mailnews.wraplength`` de ``72`` a ``0`` + +- ¡No escriba mensajes HTML! Acuda a la ventana principal + :menuselection:`Main Menu-->Account Settings-->youracc@server.something-->Composition & Addressing`! + Ahí puede deshabilitar la opción "Compose messages in HTML format". + +- ¡Abra mensajes solo como texto sin formato! Acuda a la ventana principal + :menuselection:`Main Menu-->View-->Message Body As-->Plain Text`! + +TkRat (GUI) +*********** + +Funciona. Utilice "Insert file..." o un editor externo. + +Gmail (Web GUI) +*************** + +No funciona para enviar parches. + +El cliente web de Gmail convierte las tabulaciones en espacios automáticamente. + +Al mismo tiempo, envuelve líneas cada 78 caracteres con saltos de línea de +estilo CRLF aunque el problema de tab2space se puede resolver con un editor +externo. + +Otro problema es que Gmail codificará en base64 cualquier mensaje que tenga +un carácter no ASCII. Eso incluye cosas como nombres europeos. diff --git a/Documentation/translations/sp_SP/process/index.rst b/Documentation/translations/sp_SP/process/index.rst new file mode 100644 index 000000000..09bfece0f --- /dev/null +++ b/Documentation/translations/sp_SP/process/index.rst @@ -0,0 +1,24 @@ +.. raw:: latex + + \renewcommand\thesection* + \renewcommand\thesubsection* + +.. include:: ../disclaimer-sp.rst + +.. _sp_process_index: + +.. toctree:: + :maxdepth: 1 + + submitting-patches + kernel-docs + coding-style + code-of-conduct + kernel-enforcement-statement + email-clients + magic-number + programming-language + deprecated + adding-syscalls + researcher-guidelines + contribution-maturity-model diff --git a/Documentation/translations/sp_SP/process/kernel-docs.rst b/Documentation/translations/sp_SP/process/kernel-docs.rst new file mode 100644 index 000000000..2f9b3df8f --- /dev/null +++ b/Documentation/translations/sp_SP/process/kernel-docs.rst @@ -0,0 +1,187 @@ +.. include:: ../disclaimer-sp.rst + +:Original: :ref:`Documentation/process/kernel-docs.rst <kernel_docs>` +:Translator: Carlos Bilbao <carlos.bilbao@amd.com> + +.. _sp_kernel_docs: + +Índice de documentación adicional del kernel +============================================ + +La necesidad de un documento como este se hizo evidente en la lista de +correo de linux-kernel cuando las mismas preguntas, solicitando sugerencias +e información, aparecieron una y otra vez. + +Afortunadamente, a medida que más y más gente accede a GNU/Linux, más +desarrolladores se interesan por el kernel. Sin embargo, leer las fuentes +no siempre es suficiente. Es fácil entender el código, pero se pierden los +conceptos, la filosofía y decisiones de diseño detrás de dicho código. + +Desafortunadamente, no existen muchos documentos disponibles para que los +principiantes comiencen. Y, aunque existieran, no habría ningún lugar +"conocido" que les pudiera seguir la pista. Estas líneas tratan de cubrir +esta carencia. + +POR FAVOR, si conoce algún documento que no figura aquí, o si escribe un +nuevo documento, incluya una referencia aquí, siguiendo el proceso de envío +de parches del kernel. Cualquier corrección, idea o comentario también es +bienvenida. + +Todos los documentos se catalogan con los siguientes campos: el "Título", +el "Autor"/es, la "URL" donde se encuentran, algunas "Palabras clave" +útiles para buscar temas específicos, y una breve "Descripción" del +documento en cuestión. + +.. note:: + + Los documentos de cada sección en este documento están ordenados por su + fecha de publicación, del más reciente al más antiguo. Los maintainers + deben ir retirando recursos obsoletos o anticuados. + +Documentos en el árbol del kernel Linux +----------------------------------------- + +Los libros de Sphinx deben compilarse con ``make {htmldocs | pdfdocs | epubdocs}``. + + * Título: **linux/Documentation** + + :Autor: Many. + :Ubicación: Documentation/ + :Palabras Clave: archivos de texto, Sphinx. + :Descripción: Documentación que viene con las fuentes del kernel, + dentro del directorio Documentation. Algunas páginas de este documento + (incluido este documento en sí) se han trasladado allí, y podrían + estar más actualizadas que la versión web. + +Documentos en línea +------------------- + + * Título: **Linux Kernel Mailing List Glossary** + + :Autor: various + :URL: https://kernelnewbies.org/KernelGlossary + :Fecha: rolling version + :Palabras Clave: glosario terminos, linux-kernel. + :Descripción: De la Introducción: "This glossary is intended as + a brief description of some of the acronyms and terms you may hear + during discussion of the Linux kernel". + + * Título: **The Linux Kernel Module Programming Guide** + + :Autor: Peter Jay Salzman, Michael Burian, Ori Pomerantz, Bob Mottram, + Jim Huang. + :URL: https://sysprog21.github.io/lkmpg/ + :Fecha: 2021 + :Palabras Clave: modules, GPL book, /proc, ioctls, system calls, + interrupt handlers, llamadas al sistema, interrupciones. + :Descripción: Un muy buen libro GPL sobre el tema de la programación + de módulos. Muchos ejemplos. Actualmente la nueva versión está + siendo mantenida activamente ent https://github.com/sysprog21/lkmpg. + +Libros publicados +----------------- + + * Título: **Linux Kernel Programming: A Comprehensive Guide to Kernel Internals, Writing Kernel Modules, and Kernel Synchronization** + + :Autor: Kaiwan N. Billimoria + :Publica: Packt Publishing Ltd + :Fecha: 2021 + :Paginas: 754 + :ISBN: 978-1789953435 + + * Título: **Linux Kernel Development, 3rd Edition** + + :Autor: Robert Love + :Publica: Addison-Wesley + :Fecha: July, 2010 + :Paginas: 440 + :ISBN: 978-0672329463 + :Notas: Libro fundacional + +.. _sp_ldd3_published: + + * Título: **Linux Device Drivers, 3rd Edition** + + :Authors: Jonathan Corbet, Alessandro Rubini, and Greg Kroah-Hartman + :Publica: O'Reilly & Associates + :Fecha: 2005 + :Paginas: 636 + :ISBN: 0-596-00590-3 + :Notas: Libro fundacional. Más información en + http://www.oreilly.com/catalog/linuxdrive3/ + formato PDF, URL: https://lwn.net/Kernel/LDD3/ + + * Título: **The Design of the UNIX Operating System** + + :Autor: Maurice J. Bach + :Publica: Prentice Hall + :Fecha: 1986 + :Paginas: 471 + :ISBN: 0-13-201757-1 + :Notas: Libro fundacional + +Recursos varios +--------------- + + * Título: **Cross-Referencing Linux** + + :URL: https://elixir.bootlin.com/ + :Palabras Clave: Browsing source code. + :Descripción: Otro navegador de código fuente del kernel Linux que se + encuentra en la web. Muchas referencias cruzadas a variables y + funciones. Puedes ver dónde se definen y dónde se utilizan. + + * Título: **Linux Weekly News** + + :URL: https://lwn.net + :Palabras Clave: latest kernel news, noticias del kernel Linux. + :Descripción: El título lo dice todo (Noticias Semanales de Linux). + Hay una sección fija sobre el kernel, resumiendo el trabajo de sus + desarrolladores, correcciones de errores, nuevas funciones y + versiones, producido durante la semana. + + * Título: **The home page of Linux-MM** + + :Autor: The Linux-MM team. + :URL: https://linux-mm.org/ + :Palabras Clave: memory management, Linux-MM, mm patches, TODO, docs, + mailing list, administración de memoria, Linux-MM, parches mm, listas + de correo. + :Descripción: Sitio dedicado al desarrollo de la gestión de memoria + de Linux. Parches relacionados con la memoria, HOWTOs, enlaces, + desarrolladores de mm... ¡Si está interesado en el desarrollo de la + gestión de memoria no te lo pierdas! + + * Título: **Kernel Newbies IRC Channel and Website** + + :URL: https://www.kernelnewbies.org + :Palabras Clave: IRC, newbies, channel, asking doubts, canal, dudas, + novatos, preguntar. + :Descripción: #kernelnewbies en irc.oftc.net. + #kernelnewbies es una red de IRC dedicada al hacker del kernel + 'novato'. La audiencia se compone principalmente de personas que + quieren aprender sobre el kernel, trabajar en proyectos del kernel + o hackers profesionales del kernel que quieren ayudar a la gente + menos experimentada. + #kernelnewbies es parte de la red OFTC IRC. + Pruebe con irc.oftc.net como su servidor y luego haga /join + #kernelnewbies. + El sitio web kernelnewbies también alberga artículos, documentos, FAQs... + + * Título: **linux-kernel mailing list archives and search engines** + + :URL: http://vger.kernel.org/vger-lists.html + :URL: http://www.uwsg.indiana.edu/hypermail/linux/kernel/index.html + :URL: http://groups.google.com/group/mlist.linux.kernel + :Palabras Clave: linux-kernel, archives, buscar, search, archivos. + :Descripción: Algunos de los archivadores de listas de correo del + kernel de Linux. Si usted tiene uno mejor/otro, por favor hágamelo + saber. + +------- + +Este documento se basaba originalmente en: + + https://www.dit.upm.es/~jmseyas/linux/kernel/hackers-docs.html + +escrito por Juan-Mariano de Goyenche diff --git a/Documentation/translations/sp_SP/process/kernel-enforcement-statement.rst b/Documentation/translations/sp_SP/process/kernel-enforcement-statement.rst new file mode 100644 index 000000000..d66902694 --- /dev/null +++ b/Documentation/translations/sp_SP/process/kernel-enforcement-statement.rst @@ -0,0 +1,174 @@ +.. include:: ../disclaimer-sp.rst + +:Original: :ref:`Documentation/process/kernel-enforcement-statement.rst <process_statement_kernel>` +:Translator: Carlos Bilbao <carlos.bilbao@amd.com> + +.. _sp_process_statement_kernel: + +Aplicación de la licencia en el kernel Linux +============================================ + +Como desarrolladores del kernel Linux, tenemos un gran interés en cómo se +se utiliza nuestro software y cómo se aplica la licencia de nuestro software. +El cumplimiento de las obligaciones de intercambio recíproco de GPL-2.0 son +fundamentales en el largo plazo para la sostenibilidad de nuestro software +y comunidad. + +Aunque existe el derecho de hacer valer un copyright distinto en las +contribuciones hechas a nuestra comunidad, compartimos el interés de +asegurar que las acciones individuales para proteger estos se lleven a cabo +de una manera que beneficia a nuestra comunidad y no tenga un indeseado +impacto negativo en la salud y crecimiento de nuestro ecosistema de software. +Con el fin de disuadir la aplicación inútil de acciones, estamos de acuerdo +en que es en el mejor interés de nuestro desarrollo como comunidad asumir +el siguiente compromiso con los usuarios del kernel Linux, en nombre +nuestro y de cualquier sucesor de nuestros derechos de autor (copyright): + + Sin perjuicio de las disposiciones de terminación de GPL-2.0, aceptamos + que es en el mejor interés de nuestra comunidad de desarrollo adoptar + las siguientes disposiciones de GPL-3.0 como permisos adicionales bajo + nuestra licencia, con respecto a cualquier interposición de alegación + de infringimiento (en inglés, "non-defensive assertion") de los + derechos bajo la licencia. + + Sin embargo, si deja de violar esta Licencia, entonces su licencia + de copyright como particular se restablece (a) provisionalmente, + a menos que y hasta que el titular de los derechos de autor explícita + y finalmente rescinda su licencia, y (b) de forma permanente, si el + titular de los derechos de autor no le notifica la violación por algún + medio razonable antes de 60 días después del cese. + + Además, su licencia de un titular de derechos de autor en particular es + restablecida permanentemente si el titular de los derechos de autor le + notifica de la violación por algún medio razonable, esta es la primera + vez que ha recibido notificación de violación de esta Licencia (para + cualquier trabajo) de ese titular de los derechos de autor, y subsana + la infracción antes de los 30 días posteriores de recibir el aviso. + +Nuestra intención al proporcionar estas garantías es fomentar un mayor uso +del software. Queremos que empresas y particulares utilicen, modifiquen y +distribuyan este software. Queremos trabajar con los usuarios de forma +abierta y transparente para eliminar cualquier incertidumbre sobre nuestras +expectativas con respecto al cumplimiento que podría limitar la adopción de +nuestro software. Entendemos la acción legal como último recurso, que se +iniciará solo cuando otros esfuerzos de la comunidad no hayan podido +resolver el problema. + +Finalmente, una vez que se resuelva un problema de incumplimiento, +esperamos que el usuario se sienta bienvenido a unirse a nosotros en +nuestros esfuerzos con este proyecto. Trabajando juntos, somos más fuertes. + +Excepto donde se indica a continuación, hablamos solo por nosotros mismos y +no por ninguna compañía donde puede que trabajemos hoy, o hayamos trabajado +en el pasado, o trabajaremos en el futuro. + +- Laura Abbott +- Bjorn Andersson (Linaro) +- Andrea Arcangeli +- Neil Armstrong +- Jens Axboe +- Pablo Neira Ayuso +- Khalid Aziz +- Ralf Baechle +- Felipe Balbi +- Arnd Bergmann +- Ard Biesheuvel +- Tim Bird +- Paolo Bonzini +- Christian Borntraeger +- Mark Brown (Linaro) +- Paul Burton +- Javier Martinez Canillas +- Rob Clark +- Kees Cook (Google) +- Jonathan Corbet +- Dennis Dalessandro +- Vivien Didelot (Savoir-faire Linux) +- Hans de Goede +- Mel Gorman (SUSE) +- Sven Eckelmann +- Alex Elder (Linaro) +- Fabio Estevam +- Larry Finger +- Bhumika Goyal +- Andy Gross +- Juergen Gross +- Shawn Guo +- Ulf Hansson +- Stephen Hemminger (Microsoft) +- Tejun Heo +- Rob Herring +- Masami Hiramatsu +- Michal Hocko +- Simon Horman +- Johan Hovold (Hovold Consulting AB) +- Christophe JAILLET +- Olof Johansson +- Lee Jones (Linaro) +- Heiner Kallweit +- Srinivas Kandagatla +- Jan Kara +- Shuah Khan (Samsung) +- David Kershner +- Jaegeuk Kim +- Namhyung Kim +- Colin Ian King +- Jeff Kirsher +- Greg Kroah-Hartman (Linux Foundation) +- Christian König +- Vinod Koul +- Krzysztof Kozlowski +- Viresh Kumar +- Aneesh Kumar K.V +- Julia Lawall +- Doug Ledford +- Chuck Lever (Oracle) +- Daniel Lezcano +- Shaohua Li +- Xin Long +- Tony Luck +- Catalin Marinas (Arm Ltd) +- Mike Marshall +- Chris Mason +- Paul E. McKenney +- Arnaldo Carvalho de Melo +- David S. Miller +- Ingo Molnar +- Kuninori Morimoto +- Trond Myklebust +- Martin K. Petersen (Oracle) +- Borislav Petkov +- Jiri Pirko +- Josh Poimboeuf +- Sebastian Reichel (Collabora) +- Guenter Roeck +- Joerg Roedel +- Leon Romanovsky +- Steven Rostedt (VMware) +- Frank Rowand +- Ivan Safonov +- Anna Schumaker +- Jes Sorensen +- K.Y. Srinivasan +- David Sterba (SUSE) +- Heiko Stuebner +- Jiri Kosina (SUSE) +- Willy Tarreau +- Dmitry Torokhov +- Linus Torvalds +- Thierry Reding +- Rik van Riel +- Luis R. Rodriguez +- Geert Uytterhoeven (Glider bvba) +- Eduardo Valentin (Amazon.com) +- Daniel Vetter +- Linus Walleij +- Richard Weinberger +- Dan Williams +- Rafael J. Wysocki +- Arvind Yadav +- Masahiro Yamada +- Wei Yongjun +- Lv Zheng +- Marc Zyngier (Arm Ltd) + 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 000000000..7c7dfb4ba --- /dev/null +++ b/Documentation/translations/sp_SP/process/magic-number.rst @@ -0,0 +1,89 @@ +.. 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`` +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`` +===================== ================ ======================== ========================================== diff --git a/Documentation/translations/sp_SP/process/programming-language.rst b/Documentation/translations/sp_SP/process/programming-language.rst new file mode 100644 index 000000000..301f52537 --- /dev/null +++ b/Documentation/translations/sp_SP/process/programming-language.rst @@ -0,0 +1,53 @@ +.. include:: ../disclaimer-sp.rst + +:Original: :ref:`Documentation/process/programming-language.rst <programming_language>` +:Translator: Carlos Bilbao <carlos.bilbao@amd.com> + +.. _sp_programming_language: + +Lenguaje de programación +======================== + +El kernel está escrito en el lenguaje de programación C [sp-c-language]_. +Más concretamente, el kernel normalmente se compila con ``gcc`` [sp-gcc]_ +bajo ``-std=gnu11`` [sp-gcc-c-dialect-options]_: el dialecto GNU de ISO C11. +``clang`` [sp-clang]_ también es compatible, consulte los documentos en +:ref:`Building Linux with Clang/LLVM <kbuild_llvm>`. + +Este dialecto contiene muchas extensiones del lenguaje [sp-gnu-extensions]_, +y muchos de ellos se usan dentro del kernel de forma habitual. + +Hay algo de soporte para compilar el núcleo con ``icc`` [sp-icc]_ para varias +de las arquitecturas, aunque en el momento de escribir este texto, eso no +está terminado y requiere parches de terceros. + +Atributos +--------- + +Una de las comunes extensiones utilizadas en todo el kernel son los atributos +[sp-gcc-attribute-syntax]_. Los atributos permiten introducir semántica +definida por la implementación a las entidades del lenguaje (como variables, +funciones o tipos) sin tener que hacer cambios sintácticos significativos +al idioma (por ejemplo, agregar una nueva palabra clave) [sp-n2049]_. + +En algunos casos, los atributos son opcionales (es decir, hay compiladores +que no los admiten pero de todos modos deben producir el código adecuado, +incluso si es más lento o no realiza tantas comprobaciones/diagnósticos en +tiempo de compilación). + +El kernel define pseudo-palabras clave (por ejemplo, ``__pure``) en lugar +de usar directamente la sintaxis del atributo GNU (por ejemplo, +``__attribute__((__pure__))``) con el fin de detectar cuáles se pueden +utilizar y/o acortar el código. + +Por favor consulte ``include/linux/compiler_attributes.h`` para obtener +más información. + +.. [sp-c-language] http://www.open-std.org/jtc1/sc22/wg14/www/standards +.. [sp-gcc] https://gcc.gnu.org +.. [sp-clang] https://clang.llvm.org +.. [sp-icc] https://software.intel.com/en-us/c-compilers +.. [sp-gcc-c-dialect-options] https://gcc.gnu.org/onlinedocs/gcc/C-Dialect-Options.html +.. [sp-gnu-extensions] https://gcc.gnu.org/onlinedocs/gcc/C-Extensions.html +.. [sp-gcc-attribute-syntax] https://gcc.gnu.org/onlinedocs/gcc/Attribute-Syntax.html +.. [sp-n2049] http://www.open-std.org/jtc1/sc22/wg14/www/docs/n2049.pdf diff --git a/Documentation/translations/sp_SP/process/researcher-guidelines.rst b/Documentation/translations/sp_SP/process/researcher-guidelines.rst new file mode 100644 index 000000000..462b3290b --- /dev/null +++ b/Documentation/translations/sp_SP/process/researcher-guidelines.rst @@ -0,0 +1,150 @@ +.. SPDX-License-Identifier: GPL-2.0 + +:Original: :ref:`Documentation/process/researcher-guidelines.rst` +:Translator: Avadhut Naik <avadhut.naik@amd.com> + +Directrices para Investigadores +++++++++++++++++++++++++++++++++ + +La comunidad del kernel de Linux da la bienvenida a la investigación +transparente sobre el kernel de Linux, las actividades involucradas +en su producción, otros subproductos de su desarrollo. Linux se +beneficia mucho de este tipo de investigación, y la mayoría de los +aspectos de Linux son impulsados por investigación en una forma u otra. + +La comunidad agradece mucho si los investigadores pueden compartir +los hallazgos preliminares antes de hacer públicos sus resultados, +especialmente si tal investigación involucra seguridad. Involucrarse +temprano ayuda a mejorar la calidad de investigación y la capacidad +de Linux para mejorar a partir de ella. En cualquier caso, se recomienda +compartir copias de acceso abierto de la investigación publicada con +la comunidad. + +Este documento busca clarificar lo que la comunidad del kernel de Linux +considera practicas aceptables y no aceptables al llevar a cabo +investigación de este tipo. Por lo menos, dicha investigación y +actividades afines deben seguir las reglas estándar de ética de la +investigación. Para más información sobre la ética de la investigación +en general, ética en la tecnología y la investigación de las comunidades +de desarrolladores en particular, ver: + + +* `Historia de la Ética en la Investigación <https://www.unlv.edu/research/ORI-HSR/history-ethics>`_ +* `Ética de la IEEE <https://www.ieee.org/about/ethics/index.html>`_ +* `Perspectivas de Desarrolladores e Investigadores sobre la Ética de los Experimentos en Proyectos de Código Abierto <https://arxiv.org/pdf/2112.13217.pdf>`_ + +La comunidad del kernel de Linux espera que todos los que interactúan con +el proyecto están participando en buena fe para mejorar Linux. La +investigación sobre cualquier artefacto disponible públicamente (incluido, +pero no limitado a código fuente) producido por la comunidad del kernel +de Linux es bienvenida, aunque la investigación sobre los desarrolladores +debe ser claramente opcional. + +La investigación pasiva que se basa completamente en fuentes disponibles +públicamente, incluidas las publicaciones en listas de correo públicas y +las contribuciones a los repositorios públicos, es claramente permitida. +Aunque, como con cualquier investigación, todavía se debe seguir la ética +estándar. + +La investigación activa sobre el comportamiento de los desarrolladores, +sin embargo, debe hacerse con el acuerdo explícito y la divulgación +completa a los desarrolladores individuales involucrados. No se puede +interactuar / experimentar con los desarrolladores sin consentimiento; +esto también es ética de investigación estándar. + +Para ayudar a aclarar: enviar parches a los desarrolladores es interactuar +con ellos, pero ya han dado su consentimiento para recibir contribuciones +en buena fe. No se ha dado consentimiento para enviar parches intencionalmente +defectuosos / vulnerables o contribuir con la información engañosa a las +discusiones. Dicha comunicación puede ser perjudicial al desarrollador (por +ejemplo, agotar el tiempo, el esfuerzo, y la moral) y perjudicial para el +proyecto al erosionar la confianza de toda la comunidad de desarrolladores en +el colaborador (y la organización del colaborador en conjunto), socavando +los esfuerzos para proporcionar reacciones constructivas a los colaboradores +y poniendo a los usuarios finales en riesgo de fallas de software. + +La participación en el desarrollo de Linux en sí mismo por parte de +investigadores, como con cualquiera, es bienvenida y alentada. La +investigación del código de Linux es una práctica común, especialmente +cuando se trata de desarrollar o ejecutar herramientas de análisis que +producen resultados procesables. + +Cuando se interactúa con la comunidad de desarrolladores, enviar un +parche ha sido tradicionalmente la mejor manera para hacer un impacto. +Linux ya tiene muchos errores conocidos – lo que es mucho más útil es +tener soluciones verificadas. Antes de contribuir, lea cuidadosamente +la documentación adecuada. + +* Documentation/process/development-process.rst +* Documentation/process/submitting-patches.rst +* Documentation/admin-guide/reporting-issues.rst +* Documentation/process/security-bugs.rst + +Entonces envíe un parche (incluyendo un registro de confirmación con +todos los detalles enumerados abajo) y haga un seguimiento de cualquier +comentario de otros desarrolladores. + +* ¿Cuál es el problema específico que se ha encontrado? +* ¿Como podría llegar al problema en un sistema en ejecución? +* ¿Qué efecto tendría encontrar el problema en el sistema? +* ¿Como se encontró el problema? Incluya específicamente detalles sobre + cualquier prueba, programas de análisis estáticos o dinámicos, y cualquier + otra herramienta o método utilizado para realizar el trabajo. +* ¿En qué versión de Linux se encontró el problema? Se prefiere usar la + versión más reciente o una rama reciente de linux-next (ver + Documentation/process/howto.rst). +* ¿Que se cambió para solucionar el problema y por qué se cree es correcto? +* ¿Como se probó el cambio para la complicación y el tiempo de ejecución? +* ¿Qué confirmación previa corrige este cambio? Esto debería ir en un “Fixes:” + etiqueta como se describe en la documentación. +* ¿Quién más ha revisado este parche? Esto debería ir con la adecuada “Reviewed-by” + etiqueta; Vea abajo. + +Por ejemplo (en inglés, pues es en las listas):: + + From: Author <author@email> + Subject: [PATCH] drivers/foo_bar: Add missing kfree() + + The error path in foo_bar driver does not correctly free the allocated + struct foo_bar_info. This can happen if the attached foo_bar device + rejects the initialization packets sent during foo_bar_probe(). This + would result in a 64 byte slab memory leak once per device attach, + wasting memory resources over time. + + This flaw was found using an experimental static analysis tool we are + developing, LeakMagic[1], which reported the following warning when + analyzing the v5.15 kernel release: + + path/to/foo_bar.c:187: missing kfree() call? + + Add the missing kfree() to the error path. No other references to + this memory exist outside the probe function, so this is the only + place it can be freed. + + x86_64 and arm64 defconfig builds with CONFIG_FOO_BAR=y using GCC + 11.2 show no new warnings, and LeakMagic no longer warns about this + code path. As we don't have a FooBar device to test with, no runtime + testing was able to be performed. + + [1] https://url/to/leakmagic/details + + Reported-by: Researcher <researcher@email> + Fixes: aaaabbbbccccdddd ("Introduce support for FooBar") + Signed-off-by: Author <author@email> + Reviewed-by: Reviewer <reviewer@email> + +Si usted es un colaborador por primera vez, se recomienda que el parche en +si sea examinado por otros en privado antes de ser publicado en listas +públicas. (Esto es necesario si se le ha dicho explícitamente que sus parches +necesitan una revisión interna más cuidadosa.) Se espera que estas personas +tengan su etiqueta “Reviewed-by” incluida en el parche resultante. Encontrar +otro desarrollador con conocimiento de las contribuciones a Linux, especialmente +dentro de su propia organización, y tener su ayuda con las revisiones antes de +enviarlas a las listas de correo publico tiende a mejorar significativamente la +calidad de los parches resultantes, y reduce así la carga de otros desarrolladores. + +Si no se puede encontrar a nadie para revisar internamente los parches y necesita +ayuda para encontrar a esa persona, o si tiene alguna otra pregunta relacionada +con este documento y las expectativas de la comunidad de desarrolladores, por +favor contacte con la lista de correo privada Technical Advisory Board: +<tech-board@lists.linux-foundation.org>. diff --git a/Documentation/translations/sp_SP/process/submitting-patches.rst b/Documentation/translations/sp_SP/process/submitting-patches.rst new file mode 100644 index 000000000..c2757d9ab --- /dev/null +++ b/Documentation/translations/sp_SP/process/submitting-patches.rst @@ -0,0 +1,894 @@ +.. include:: ../disclaimer-sp.rst + +:Original: :ref:`Documentation/process/submitting-patches.rst <submittingpatches>` +:Translator: Carlos Bilbao <carlos.bilbao@amd.com> + +.. _sp_submittingpatches: + +Envío de parches: la guía esencial para incluir su código en el kernel +======================================================================= + +Para una persona o empresa que desee enviar un cambio al kernel Linux, +el proceso puede en ocasiones resultar desalentador si no se está +familiarizado con "el sistema". Este texto es una colección de sugerencias +que pueden aumentar considerablemente las posibilidades de que se acepte su +cambio. + +Este documento contiene una gran cantidad de sugerencias en un formato +relativamente conciso. Para obtener información detallada sobre cómo +funciona el proceso de desarrollo del kernel, consulte +Documentation/process/development-process.rst. Además, lea +Documentation/process/submit-checklist.rst para obtener una lista de +elementos a verificar antes de enviar código. Para los parches de +"binding" del árbol de dispositivos, lea +Documentation/devicetree/bindings/submitting-patches.rst. + +Esta documentación asume que está usando ``git`` para preparar sus parches. +Si no está familiarizado con ``git``, le recomendamos que aprenda a +usarlo, le hará la vida como desarrollador del kernel y en general mucho +más sencilla. + +Algunos subsistemas y árboles de mantenimiento cuentan con información +adicional sobre su flujo de trabajo y expectativas, consulte +:ref:`Documentation/process/maintainer-handbooks.rst <maintainer_handbooks_main>`. + +Obtenga el código fuente actual +-------------------------------- + +Si no tiene a mano un repositorio con el código fuente actual del kernel, +use ``git`` para obtener uno. Querrá comenzar con el repositorio principal, +que se puede descargar con:: + + git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git + +Tenga en cuenta, sin embargo, que es posible que no desee desarrollar con +el árbol principal directamente. La mayoría de los maintainers de +subsistemas usan sus propios árboles de código fuente y quieren ver parches +preparados para esos árboles. Revise el campo **T:** para el subsistema +en el archivo MAINTAINERS para encontrar dicho árbol, o simplemente +pregunte al maintainer si el árbol no está listado allí. + +.. _sp_describe_changes: + +Describa sus cambios +--------------------- + +Describa su problema. Sea su parche una corrección de un error de una +línea o 5000 líneas para una nuevo "feature", debe haber un problema +subyacente que le motivó a hacer ese trabajo. Convenza al revisor de que +hay un problema que merece la pena solucionar y de que tiene sentido que +lea más allá del primer párrafo. + +Describa el impacto relativo al usuario. Cosas que estropeen el kernel y +los bloqueos son bastante convincentes, pero no todos los errores son tan +evidentes. Incluso si se detectó un problema durante la revisión del +código, describa el impacto que cree pueda tener en los usuarios. Tenga en +cuenta que la mayoría de instalaciones de Linux ejecutan kernels desde +árboles estables secundarios o árboles específicos de proveedor/producto +que seleccionan ("cherry-pick") solo parches específicos de upstream, así +que incluya cualquier cosa que pueda ayudar a dirigir su cambio +aguas abajo: circunstancias que producen cierta situación, extractos de +dmesg, descripciones del error fatal, regresiones de rendimiento, picos de +latencia, bloqueos, etc. + +Cuantifique optimizaciones y beneficios/perdidas. Si asegura mejoras en +rendimiento, consumo de memoria, huella del stack o tamaño de binario, +incluya números que lo respalden. Pero también describa costes no obvios. +Las optimizaciones generalmente no son gratuitas, sino un equilibrio entre +CPU, memoria y legibilidad; o, cuando se trata de heurísticas, entre +diferentes cargas de trabajo. Describa las desventajas esperadas de su +optimización para que el revisor pueda comparar las perdidas con los +beneficios. + +Una vez establecido el problema, describa lo que realmente está haciendo +al respecto en detalles técnicos. Es importante describir el cambio en +lenguaje sencillo para que el revisor verifique que el código se está +comportando como se pretende. + +El maintainer le agradecerá que escriba la descripción de su parche en un +formato que se pueda incorporar fácilmente en la gestión del código fuente +del sistema, ``git``, como un "commit log" (registros de los commits). +Consulte :ref:`sp_the_canonical_patch_format`. + +Resuelva solo un problema por parche. Si su descripción comienza a ser muy +larga, eso es una señal de que probablemente necesite dividir su parche. +Lea :ref:`split_changes`. + +Cuando envíe o vuelva a enviar un parche o una serie de parches, incluya la +descripción completa del parche y justificación del mismo. No se limite a +decir que esa es la versión N del parche (serie). No espere que el +maintainer del subsistema referencie versiones de parches anteriores o use +referencias URL para encontrar la descripción del parche y colocarla en el +parche. Es decir, el parche (serie) y su descripción deben ser +independientes. Esto beneficia tanto a los maintainers como a los +revisores. Algunos revisores probablemente ni siquiera recibieran versiones +anteriores del parche. + +Describa sus cambios en la forma imperativa, por ejemplo, "hacer que xyzzy +haga frotz" en lugar de "[Este parche] hace que xyzzy haga frotz" o "[Yo] +Cambié xyzzy para que haga frotz", como si estuviera dando órdenes al +código fuente para cambiar su comportamiento. + +Si desea hacer referencia a un commit específico, no se limite a hacer +referencia al ID SHA-1 del commit. Incluya también el resumen de una línea +del commit, para que sea más fácil para los revisores saber de qué se +trata. +Ejemplo:: + + Commit e21d2170f36602ae2708 ("video: quitar platform_set_drvdata() + innecesario") eliminó innecesario platform_set_drvdata(), pero dejó la + variable "dev" sin usar, bórrese. + +También debe asegurarse de utilizar al menos los primeros doce caracteres +del identificador SHA-1. El repositorio del kernel contiene muchos *muchos* +objetos, por lo que las colisiones con identificaciones más cortas son una +posibilidad real. Tenga en cuenta que, aunque no hay colisión con su +identificación de seis caracteres ahora, esa condición puede cambiar dentro +de cinco años. + +Si las discusiones relacionadas o cualquier otra información relativa al +cambio se pueden encontrar en la web, agregue las etiquetas 'Link:' que +apunten a estos. En caso de que su parche corrija un error, por poner un +ejemplo, agregue una etiqueta con una URL que haga referencia al informe en +los archivos de las listas de correo o un rastreador de errores; si el +parche es el resultado de alguna discusión anterior de la lista de correo o +algo documentado en la web, referencie esto. + +Cuando se vincule a archivos de listas de correo, preferiblemente use el +servicio de archivador de mensajes lore.kernel.org. Para crear la URL del +enlace, utilice el contenido del encabezado ("header") ``Message-Id`` del +mensaje sin los corchetes angulares que lo rodean. +Por ejemplo:: + + Link: https://lore.kernel.org/r/30th.anniversary.repost@klaava.Helsinki.FI/ + +Verifique el enlace para asegurarse de que realmente funciona y apunta al +mensaje correspondiente. + +Sin embargo, intente que su explicación sea comprensible sin recursos +externos. Además de dar una URL a un archivo o error de la lista de correo, +resuma los puntos relevantes de la discusión que condujeron al parche tal y +como se envió. + +Si su parche corrige un error en un commit específico, por ejemplo +encontró un problema usando ``git bisect``, utilice la etiqueta 'Fixes:' +con los primeros 12 caracteres del ID SHA-1 y el resumen de una línea. No +divida la etiqueta en varias líneas, las etiquetas están exentas de la +regla "ajustar a 75 columnas" para simplificar análisis de scripts. Por +ejemplo:: + + Fixes: 54a4f0239f2e ("KVM: MMU: hacer que kvm_mmu_zap_page() + devuelva la cantidad de páginas que realmente liberó") + +Las siguientes configuraciones de ``git config`` se pueden usar para +agregar un bonito formato y generar este estilo con los comandos +``git log`` o ``git show``:: + + [core] + abbrev = 12 + [pretty] + fixes = Fixes: %h (\"%s\") + +Un ejemplo de uso:: + + $ git log -1 --pretty=fixes 54a4f0239f2e + Fixes: 54a4f0239f2e ("KVM: MMU: hacer que kvm_mmu_zap_page() devuelva la cantidad de páginas que realmente liberó") + +.. _sp_split_changes: + +Separe sus cambios +------------------- + +Separe cada **cambio lógico** en un parche separado. + +Por ejemplo, si sus cambios incluyen correcciones de errores y mejoras en +el rendimiento de un controlador, separe esos cambios en dos o más parches. +Si sus cambios incluyen una actualización de la API y una nueva controlador +que usa esta nueva API, sepárelos en dos parches. + +Por otro lado, si realiza un solo cambio en numerosos archivos, agrupe esos +cambios en un solo parche. Por lo tanto, un solo cambio lógico estará +contenido en un solo parche. + +El punto a recordar es que cada parche debe realizar un cambio que puede +ser verificado por los revisores fácilmente. Cada parche debe ser +justificable por sus propios méritos. + +Si un parche depende de otro parche para que un cambio sea completo, eso +está bien. Simplemente incluya que **"este parche depende del parche X"** +en la descripción de su parche. + +Cuando divida su cambio en una serie de parches, tenga especial cuidado en +asegurarse de que el kernel se compila y ejecuta correctamente después de +cada parche en la serie. Los desarrolladores que usan ``git bisect`` +para rastrear un problema pueden terminar dividiendo su serie de parches en +cualquier punto; no le agradecerán si introdujo errores a la mitad. + +Si no puede condensar su conjunto de parches en un conjunto más pequeño de +parches, solo publique, más o menos 15 a la vez, y espere la revisión e +integración. + + +Revise el estilo en sus cambios +-------------------------------- + +Revise su parche para ver si hay violaciones de estilo básico, cuyos +detalles pueden ser encontrados en Documentation/process/coding-style.rst. +No hacerlo simplemente desperdicia el tiempo de los revisores y su parche +será rechazado, probablemente sin siquiera ser leído. + +Una excepción importante es cuando se mueve código de un archivo a otro. +En tal caso, en absoluto debe modificar el código movido en el mismo parche +en que lo mueve. Esto divide claramente el acto de mover el código y sus +cambios. Esto ayuda mucho a la revisión de la diferencias reales y permite +que las herramientas rastreen mejor el historial del código en sí. + +Verifique sus parches con el verificador de estilo de parches antes de +enviarlos (scripts/checkpatch.pl). Tenga en cuenta, sin embargo, que el +verificador de estilo debe ser visto como una guía, no como un reemplazo +del juicio humano. Si su código es mejor con una violación entonces +probablemente sea mejor dejarlo estar. + +El verificador informa a tres niveles: + - ERROR: cosas que es muy probable que estén mal + - WARNING: Advertencia. Cosas que requieren una revisión cuidadosa + - CHECK: Revisar. Cosas que requieren pensarlo + +Debe poder justificar todas las violaciones que permanezcan en su parche. + + +Seleccione los destinatarios de su parche +------------------------------------------ + +Siempre debe incluir en copia a los apropiados maintainers del subsistema +en cualquier parche con código que mantengan; revise a través del archivo +MAINTAINERS y el historial de revisión del código fuente para ver quiénes +son esos maintainers. El script scripts/get_maintainer.pl puede ser muy +útil en este paso (pase rutas a sus parches como argumentos para +scripts/get_maintainer.pl). Si no puede encontrar un maintainer del +subsistema en el que está trabajando, Andrew Morton +(akpm@linux-foundation.org) sirve como maintainer de último recurso. + +Normalmente, también debe elegir al menos una lista de correo para recibir +una copia de su conjunto de parches. linux-kernel@vger.kernel.org debe +usarse de forma predeterminada para todos los parches, pero el volumen en +esta lista ha hecho que muchos desarrolladores se desconecten. Busque en el +archivo MAINTAINERS una lista específica de los subsistemas; su parche +probablemente recibirá más atención allí. Sin embargo, no envíe spam a +listas no relacionadas. + +Muchas listas relacionadas con el kernel están alojadas en vger.kernel.org; +puedes encontrar un listado de estas en +http://vger.kernel.org/vger-lists.html. Existen listas relacionadas con el +kernel alojadas en otros lugares, no obstante. + +¡No envíe más de 15 parches a la vez a las listas de correo de vger! + +Linus Torvalds es el árbitro final de todos los cambios aceptados en el +kernel de Linux. Su dirección de correo electrónico es +<torvalds@linux-foundation.org>. Recibe muchos correos electrónicos y, en +este momento, muy pocos parches pasan por Linus directamente, por lo que +normalmente debe hacer todo lo posible para -evitar- enviarle un correo +electrónico. + +Si tiene un parche que corrige un error de seguridad explotable, envíe ese +parche a security@kernel.org. Para errores graves, se debe mantener un +poco de discreción y permitir que los distribuidores entreguen el parche a +los usuarios; en esos casos, obviamente, el parche no debe enviarse a +ninguna lista pública. Revise también +Documentation/process/security-bugs.rst. + +Los parches que corrigen un error grave en un kernel en uso deben dirigirse +hacia los maintainers estables poniendo una línea como esta:: + + CC: stable@vger.kernel.org + +en el área de sign-off de su parche (es decir, NO un destinatario de correo +electrónico). También debe leer +Documentation/process/stable-kernel-rules.rst además de este documento. + +Si los cambios afectan las interfaces del kernel para el usuario, envíe al +maintainer de las MAN-PAGES (como se indica en el archivo MAINTAINERS) un +parche de páginas de manual, o al menos una notificación del cambio, para +que alguna información se abra paso en las páginas del manual. Los cambios +de la API del espacio de usuario también deben copiarse en +linux-api@vger.kernel.org. + + +Sin MIME, enlaces, compresión o archivos adjuntos. Solo texto plano +-------------------------------------------------------------------- + +Linus y otros desarrolladores del kernel deben poder leer y comentar sobre +los cambios que está enviando. Es importante para un desarrollador kernel +poder "citar" sus cambios, utilizando herramientas estándar de correo +electrónico, de modo que puedan comentar sobre partes específicas de su +código. + +Por este motivo, todos los parches deben enviarse por correo electrónico +"inline". La forma más sencilla de hacerlo es con ``git send-email``, que +es muy recomendable. Un tutorial interactivo para ``git send-email`` está +disponible en https://git-send-email.io. + +Si elige no usar ``git send-email``: + +.. warning:: + + Tenga cuidado con el ajuste de palabras de su editor que corrompe su + parche, si elige cortar y pegar su parche. + +No adjunte el parche como un archivo adjunto MIME, comprimido o no. Muchas +populares aplicaciones de correo electrónico no siempre transmiten un MIME +archivo adjunto como texto sin formato, por lo que es imposible comentar +en su código. Linus también necesita un poco más de tiempo para procesar un +archivo adjunto MIME, disminuyendo la probabilidad de que se acepte su +cambio adjunto en MIME. + +Excepción: si su proveedor de correo está destrozando parches, entonces +alguien puede pedir que los vuelva a enviar usando MIME. + +Consulte Documentation/process/email-clients.rst para obtener sugerencias +sobre cómo configurar su cliente de correo electrónico para que envíe sus +parches intactos. + +Responda a los comentarios de revisión +--------------------------------------- + +Es casi seguro que su parche recibirá comentarios de los revisores sobre +maneras en que se pueda mejorar el parche, en forma de respuesta a su +correo electrónico. Debe responder a esos comentarios; ignorar a los +revisores es una buena manera de ser ignorado de vuelta. Simplemente puede +responder a sus correos electrónicos para contestar a sus comentarios. +Revisiones a los comentarios o preguntas que no conduzcan a un cambio de +código deben casi con certeza generar un comentario o una entrada en el +"changelog" para que el próximo revisor entienda lo que está pasando. + +Asegúrese de decirles a los revisores qué cambios está haciendo y de +agradecerles que dediquen su tiempo. La revisión del código es un proceso +agotador y lento, y los revisores a veces se ponen de mal humor. Sin +embargo, incluso en ese caso, responda cortésmente y aborde los problemas +que hayan señalado. Al enviar un siguiente versión, agregue un +``patch changelog`` (registro de cambios en los parches) a la carta de +presentación ("cover letter") o a parches individuales explicando la +diferencia con la presentación anterior (ver +:ref:`sp_the_canonical_patch_format`). + +Consulte Documentation/process/email-clients.rst para obtener +recomendaciones sobre clientes de correo electrónico y normas de etiqueta +en la lista de correo. + +.. _sp_resend_reminders: + +No se desanime o impaciente +--------------------------- + +Después de haber entregado su cambio, sea paciente y espere. Los revisores +son personas ocupadas y es posible que no lleguen a su parche de inmediato. + +Érase una vez, los parches solían desaparecer en el vacío sin comentarios, +pero el proceso de desarrollo funciona mejor que eso ahora. Debería +recibir comentarios dentro de una semana más o menos; si eso no sucede, +asegúrese de que ha enviado sus parches al lugar correcto. Espere un mínimo +de una semana antes de volver a enviar o hacer ping a los revisores, +posiblemente más durante periodos de mucho trabajo ocupados como "merge +windows". + +También está bien volver a enviar el parche o la serie de parches después +de un par de semanas con la palabra "RESEND" (reenviar) añadida a la línea +de asunto:: + + [PATCH Vx RESEND] sub/sys: Resumen condensado de parche + +No incluya "RESEND" cuando envíe una versión modificada de su parche o +serie de parches: "RESEND" solo se aplica al reenvío de un parche o serie +de parches que no hayan sido modificados de ninguna manera con respecto a +la presentación anterior. + + +Incluya PATCH en el asunto +-------------------------- + +Debido al alto tráfico de correo electrónico a Linus y al kernel de Linux, +es común prefijar su línea de asunto con [PATCH]. Esto le permite a Linus +y otros desarrolladores del kernel distinguir más fácilmente los parches de +otras discusiones por correo electrónico. + +``git send-email`` lo hará automáticamente. + + +Firme su trabajo: el Certificado de Origen del Desarrollador +------------------------------------------------------------ + +Para mejorar el seguimiento de quién hizo qué, especialmente con parches +que pueden filtrarse hasta su destino final a través de varias capas de +maintainers, hemos introducido un procedimiento de "sign-off" (aprobación) +en parches que se envían por correo electrónico. + +La aprobación es una simple línea al final de la explicación del parche, +que certifica que usted lo escribió o que tiene derecho a enviarlo como un +parche de código abierto. Las reglas son bastante simples: si usted puede +certificar lo siguiente: + +Certificado de Origen del Desarrollador 1.1 +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Al hacer una contribución a este proyecto, certifico que: + + (a) La contribución fue creada en su totalidad o en parte por mí y + tengo derecho a enviarlo bajo la licencia de código abierto + indicada en el documento; o + + (b) La contribución se basa en trabajo previo que, hasta donde yo + soy consciente, está cubierto por una licencia de código + abierto apropiada y tengo el derecho bajo esa licencia de + presentar tal trabajo con modificaciones, ya sean creadas en su + totalidad o en parte por mí, bajo la misma licencia de código + (salvo que sea permitido presentar bajo una licencia diferente), + tal y como se indica en el documento; o + + (c) La contribución me fue proporcionada directamente por alguna + otra persona que certificó (a), (b) o (c) y no he modificado + esto. + + (d) Entiendo y acepto que este proyecto y la contribución + son públicos y que un registro de la contribución (incluyendo + toda la información personal que envío con él, incluida mi + firma) es mantenida indefinidamente y puede ser redistribuida + de manera consistente con este proyecto o la(s) licencia(s) de + código abierto involucradas. + +entonces simplemente incluya una línea que rece:: + + Signed-off-by: Random J Developer <random@developer.example.org> + +usando su nombre real (lamentablemente, no pseudónimos ni contribuciones +anónimas). Esto se hará por usted automáticamente si usa ``git commit -s``. +Las reversiones de código también deben incluir "Signed-off-by". +``git revert -s`` hace eso por usted. + +Algunas personas también ponen etiquetas adicionales al final. Simplemente +serán ignoradas por ahora, pero puede hacer esto para marcar procedimientos +internos de su empresa o simplemente señalar algún detalle especial sobre +la firma. + +Cualquier otro SoB (Signed-off-by:) después del SoB del autor es de +personas que manipulen y transporten el parche, pero no participaron en su +desarrollo. Las cadenas de SoB deben reflejar la ruta **real** del parche +de cómo se propagó a los maintainers y, en última instancia, a Linus, con +la primera entrada de SoB que señala la autoría principal de un solo autor. + + +Cuándo usar Acked-by:, Cc: y Co-developed-by por: +------------------------------------------------- + +La etiqueta Signed-off-by: indica que el firmante estuvo involucrado en el +desarrollo del parche, o que él/ella se encontraba en el camino de entrega +del parche. + +Si una persona no estuvo directamente involucrada en la preparación o +administración de un parche pero desea expresar y registrar su aprobación, +entonces puede pedir que se agregue una línea Acked-by: al registro de +cambios del parche. + +Acked-by: a menudo lo usa el maintainer del código afectado cuando ese +maintainer no contribuyó ni envió el parche. + +Acked-by: no es tan formal como Signed-off-by:. Es una manera de marcar que +el "acker" ha revisado al menos ese parche y ha indicado su aceptación. Por +los merge de parches a veces convertirán manualmente el "sí, me parece bien" +de un acker en un Acked-by: (pero tenga en cuenta que por lo general es +mejor pedir un acuse de recibo explícito). + +Acked-by: no necesariamente indica el reconocimiento de todo el parche. +Por ejemplo, si un parche afecta a varios subsistemas y tiene un +Acked-by: de un maintainer del subsistema, entonces esto generalmente +indica el reconocimiento de solo la parte que afecta el código de ese +maintainer. Buen juicio debe ejercitarse aquí. En caso de duda, la gente +debe consultar la discusión original en los archivos de la lista de correo. + +Si una persona ha tenido la oportunidad de comentar un parche, pero no lo +ha hecho, puede incluir opcionalmente una etiqueta ``Cc:`` al parche. +Esta es la única etiqueta que se puede agregar sin una acción explícita por +parte de la persona a la que se nombre - pero debe indicar que esta persona +fue copiada en el parche. Esta etiqueta documenta que las partes +potencialmente interesadas han sido incluidas en la discusión. + +Co-developed-by: establece que el parche fue co-creado por múltiples +desarrolladores; se utiliza para dar atribución a los coautores (además del +autor atribuido por la etiqueta From:) cuando varias personas trabajan en +un solo parche. Ya que Co-developed-by: denota autoría, cada +Co-developed-by: debe ser inmediatamente seguido de Signed-off-by: del +coautor asociado. Se mantiene el procedimiento estándar, es decir, el orden +de las etiquetas Signed-off-by: debe reflejar el historial cronológico del +parche en la medida de lo posible, independientemente de si el autor se +atribuye a través de From: o Co-developed-by:. Cabe destacar que el último +Signed-off-by: siempre debe ser del desarrollador que envía el parche. + +Tenga en cuenta que la etiqueta From: es opcional cuando el autor From: es +también la persona (y correo electrónico) enumerados en la línea From: del +encabezado del correo electrónico. + +Ejemplo de un parche enviado por el From: autor:: + + <changelog> + + Co-developed-by: Primer coautor <primer@coauthor.example.org> + Signed-off-by: Primer coautor <primer@coauthor.example.org> + Co-developed-by: Segundo coautor <segundo@coautor.ejemplo.org> + Signed-off-by: Segundo coautor <segundo@coautor.ejemplo.org> + Signed-off-by: Autor del From <from@author.example.org> + +Ejemplo de un parche enviado por un Co-developed-by: autor:: + + From: Autor del From <from@author.example.org> + + <changelog> + + Co-developed-by: Co-Autor aleatorio <aleatorio@coauthor.example.org> + Signed-off-by: Coautor aleatorio <aleatorio@coauthor.example.org> + Signed-off-by: Autor del From <from@author.example.org> + Co-developed-by: Coautor que envió <sub@coauthor.example.org> + Signed-off-by: Coautor que envía <sub@coauthor.example.org> + +Uso de Reported-by:, Tested-by:, Reviewed-by:, Suggested-by: y Fixes: +---------------------------------------------------------------------- + +La etiqueta Reported-by (Reportado-por) otorga crédito a las personas que +encuentran errores y los reportan. Por favor, tenga en cuenta que si se +informó de un error en privado, debe pedir primero permiso antes de usar la +etiqueta Reported-by. La etiqueta está destinada a errores; por favor no la +use para acreditar peticiones de características. + +Una etiqueta Tested-by: indica que el parche se probó con éxito (en algún +entorno) por la persona nombrada. Esta etiqueta informa a los maintainers +de que se han realizado algunas pruebas, proporciona un medio para ubicar +"testers" (gente que pruebe) otros parches futuros y asegura el crédito +para los testers. + +Reviewed-by: en cambio, indica que el parche ha sido revisado y encontrado +aceptable de acuerdo con la Declaración del Revisor: + +Declaración de Supervisión del Revisor +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Al ofrecer mi etiqueta Reviewed-by:, afirmo que: + +(a) He llevado a cabo una revisión técnica de este parche para +evaluar su idoneidad y preparación para su inclusión en +el kernel principal. + +(b) Cualquier problema, inquietud o pregunta relacionada con el parche +han sido comunicados al remitente. Estoy satisfecho +con la respuesta del remitente a mis comentarios. + +(c) Si bien puede haber cosas que podrían mejorarse con esta +entrega, creo que es, en este momento, (1) una +modificación valiosa al kernel, y (2) libre de conocidas +cuestiones que argumentarían en contra de su inclusión. + +(d) Si bien he revisado el parche y creo que es correcto, +no hago (a menos que se indique explícitamente en otro lugar) ninguna +garantía o avales de que logrará su definido +propósito o función en cualquier situación dada. + +Una etiqueta Reviewed-by es una declaración de opinión de que el parche es +una modificación apropiada al kernel sin que haya ningún problema grave +a nivel técnico. Cualquier revisor interesado (que haya hecho el trabajo) +puede ofrecer una etiqueta Reviewed-by para un parche. Esta etiqueta sirve +para dar crédito a revisores e informar a los maintainers del grado de +revisión que se ha hecho en el parche. Las etiquetas Reviewed-by, cuando +las otorgan revisores conocidos por entender del tema y realizar +revisiones exhaustivas, normalmente aumentan la probabilidad de que su +parche entre en el kernel. + +Las etiquetas Tested-by y Reviewed-by, una vez recibidas en la lista de +correo por el tester o revisor, deben ser incluidas por el autor de los +parches pertinentes al enviar próximas versiones. Sin embargo, si el parche +ha cambiado sustancialmente en la siguiente versión, es posible que estas +etiquetas ya no sean aplicables y, por lo tanto, deben eliminarse. Por lo +general, se debe mencionar la eliminación de las etiquetas Tested-by o +Reviewed-by de alguien en el registro de cambios del parche (después del +separador '---'). + +Una etiqueta Suggested-by: indica que la idea del parche es sugerida por la +persona nombrada y asegura el crédito a la persona por la idea. Tenga en +cuenta que esto no debe agregarse sin el permiso del "reporter", +especialmente si la idea no fue publicada en un foro público. Dicho esto, +si diligentemente acreditamos a los reporters de ideas, con suerte, se +sentirán inspirados para ayudarnos nuevamente en el futuro. + +Una etiqueta Fixes: indica que el parche corrige un problema en un commit +anterior. Esto se utiliza para facilitar descubrir dónde se originó un +error, lo que puede ayudar a revisar una corrección de errores. Esta +etiqueta también ayuda al equipo del kernel estable a determinar qué +versiones estables del kernel deberían recibir su corrección. Este es el +método preferido para indicar un error corregido por el parche. Revise +:ref:`describe_changes` para más detalles. + +Nota: Adjuntar una etiqueta Fixes: no subvierte las reglas estables del +proceso del kernel ni el requisito de CC: stable@vger.kernel.org en todos +los parches candidatos de ramas estables. Para obtener más información, lea +Documentation/process/stable-kernel-rules.rst. + +.. _sp_the_canonical_patch_format: + +Formato de parche canónico +--------------------------- + +Esta sección describe cómo debe darse formato al propio parche. Tenga en +cuenta que, si tiene sus parches almacenados en un repositorio ``git``, el +parche con formato adecuado se puede obtener con ``git format-patch``. Las +herramientas no pueden crear el texto necesario, sin embargo, así que lea +las instrucciones a continuación de todos modos. + +La línea de asunto del parche canónico es:: + + Asunto: [PATCH 001/123] subsistema: frase de resumen + +El cuerpo del mensaje del parche canónico contiene lo siguiente: + + - Una línea ``from`` que especifica el autor del parche, seguida de una + línea vacía (solo es necesario si la persona que envía el parche no es + el autor). + + - El cuerpo de la explicación, línea envuelta en 75 columnas, que se + copiara en el registro de cambios permanente para describir este parche. + + - Una línea vacía. + + - Las líneas ``Signed-off-by:``, descritas anteriormente, que + también vaya en el registro de cambios. + + - Una línea de marcador que contiene simplemente ``---``. + + - Cualquier comentario adicional que no sea adecuado para el registro de + cambios. + + - El parche real (output de ``diff``). + +El formato de la línea de asunto hace que sea muy fácil ordenar los correos +electrónicos alfabéticamente por línea de asunto - prácticamente cualquier +lector de correo electrónico permite esto, ya que debido a que el número de +secuencia se rellena con ceros, el orden numérico y alfabético es el mismo. + +El ``subsistema`` en el asunto del correo electrónico debe identificar qué +área o subsistema del kernel está siendo parcheado. + +La ``frase de resumen`` en el Asunto del correo electrónico debe describir +de forma concisa el parche que contiene ese correo electrónico. La +``frase resumen`` no debe ser un nombre de archivo. No use la mismo ``frase +resumen`` para cada parche en una serie completa de parches (donde una +`` serie de parches`` (patch series) es una secuencia ordenada de múltiples +parches relacionados). + +Tenga en cuenta que la ``frase de resumen`` de su correo electrónico se +convierte en un identificador global único para ese parche. Se propaga por +hasta el registro de cambios de ``git``. La ``frase resumida`` se puede +usar más adelante en discusiones de desarrolladores que se refieran al +parche. La gente querrá buscar en Google la ``frase de resumen`` para leer +la discusión al respecto del parche. También será lo único que la gente +podrá ver rápidamente cuando, dos o tres meses después, estén pasando por +quizás miles de parches usando herramientas como ``gitk`` o ``git log +--oneline``. + +Por estas razones, el ``resumen`` no debe tener más de 70-75 caracteres, y +debe describir tanto lo que cambia el parche como por qué el parche podría +ser necesario. Es un reto ser tanto sucinto como descriptivo, pero eso es +lo que un resumen bien escrito debería hacer. + +La ``frase de resumen`` puede estar precedida por etiquetas encerradas en +corchetes: "Asunto: [PATCH <etiqueta>...] <frase de resumen>". Las +etiquetas no se consideran parte de la frase de resumen, pero describen +cómo debería ser tratado el parche. Las etiquetas comunes pueden incluir un +descriptor de versión si las múltiples versiones del parche se han enviado +en respuesta a comentarios (es decir, "v1, v2, v3") o "RFC" para indicar +una solicitud de comentarios. + +Si hay cuatro parches en una serie de parches, los parches individuales +pueden enumerarse así: 1/4, 2/4, 3/4, 4/4. Esto asegura que los +desarrolladores entiendan el orden en que se deben aplicar los parches y +que han revisado o aplicado todos los parches de la serie de parches. + +Aquí hay algunos buenos ejemplos de Asuntos:: + + Asunto: [PATCH 2/5] ext2: mejorar la escalabilidad de la búsqueda de mapas de bits + Asunto: [PATCH v2 27/01] x86: corregir el seguimiento de eflags + Asunto: [PATCH v2] sub/sys: resumen conciso del parche + Asunto: [PATCH v2 M/N] sub/sys: resumen conciso del parche + +La línea ``from`` debe ser la primera línea en el cuerpo del mensaje, +y tiene la forma:: + + From: Autor del parche <autor@ejemplo.com> + +La línea ``From`` especifica quién será acreditado como el autor del parche +en el registro de cambios permanente. Si falta la línea ``from``, entonces +la línea ``From:`` del encabezado del correo electrónico se usará para +determinar el autor del parche en el registro de cambios. + +La explicación estará incluida en el commit del changelog permanente, por +lo que debería tener sentido para un lector competente que hace mucho tiempo +ha olvidado los detalles de la discusión que podrían haber llevado a +este parche. Incluidos los síntomas del fallo que el parche trate +(mensajes de registro del kernel, mensajes de oops, etc.) son especialmente +útiles para personas que podrían estar buscando en los registros de +commits en busca de la aplicación del parche. El texto debe estar escrito +con tal detalle que cuando se lea semanas, meses o incluso años después, +pueda dar al lector la información necesaria y detalles para comprender el +razonamiento de **por qué** se creó el parche. + +Si un parche corrige una falla de compilación, puede que no sea necesario +incluir _todos_ los errores de compilación; pero lo suficiente como para +que sea probable que alguien que busque el parche puede encontrarlo. Como +en la ``frase de resumen``, es importante ser tanto sucinto como +descriptivo. + +La línea marcadora ``---`` cumple el propósito esencial de marcar para +herramientas de manejo de parches donde termina el mensaje de registro de +cambios. + +Un buen uso de los comentarios adicionales después del marcador ``---`` es +para ``diffstat``, para mostrar qué archivos han cambiado, y el número de +líneas insertadas y eliminadas por archivo. Un ``diffstat`` es +especialmente útil en parches más grandes. Si va a incluir un ``diffstat`` +después del marcador ``---``, utilice las opciones ``diffstat`` +``-p 1 -w 70`` para que los nombres de archivo se enumeran desde la parte +superior del árbol de fuentes del kernel y no use demasiado espacio +horizontal (que encaje fácilmente en 80 columnas, tal vez con alguna +indentación). (``git`` genera diffstats apropiados por defecto). + +Otros comentarios relevantes solo en el momento o para el maintainer, pero +no adecuados para el registro de cambios permanente, también debe ir aquí. +Un buen ejemplo de tales comentarios podría ser ``registros de cambios de +parches`` que describen qué ha cambiado entre la versión v1 y v2 del +parche. + +Por favor, ponga esta información **después** de la línea ``---`` que +separa el registro de cambios del resto del parche. La información de la +versión no forma parte del registro de cambios que se incluye con el árbol +git. Es información adicional para los revisores. Si se coloca encima de la +etiquetas de commit, necesita interacción manual para eliminarlo. Si esta +debajo de la línea de separación, se quita automáticamente al aplicar el +parche:: + + <mensaje de commit> + ... + Signed-off-by: Autor <autor@correo> + --- + V2 -> V3: función auxiliar redundante eliminada + V1 -> V2: estilo de código limpio y comentarios de revisión abordados + + ruta/al/archivo | 5+++-- + ... + +Revise más detalles sobre el formato de parche adecuado en las siguientes +referencias + +.. _sp_backtraces: + +Retrocesos en mensajes de confirmación +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Los "backtraces" (deshacer el camino) ayuda a documentar la cadena de +llamadas que conducen a un problema. Sin embargo, no todos los rastreos son +útiles. Por ejemplo, las tempranas cadenas de llamadas de inicio son únicas +y obvias. Sin embargo, al copiar la salida completa de dmesg textualmente, +incluye información que distrae, como marcas de tiempo, listas de módulos, +registro y volcados de pila. + +Por lo tanto, los backtraces más útiles deben contener los datos +relevantes de la información vertida, lo que hace que sea más fácil +centrarse en el verdadero tema. Este es un ejemplo de un backtrace bien +recortado:: + + error de acceso de MSR no verificado: WRMSR a 0xd51 (intentó escribir 0x0000000000000064) + en rIP: 0xffffffffae059994 (native_write_msr+0x4/0x20) + Rastreo de llamadas: + mba_wrmsr + update_domains + rdtgroup_mkdir + +.. _sp_explicit_in_reply_to: + +In-Reply-To explicitos en las cabeceras +--------------------------------------- + +Puede ser útil agregar manualmente encabezados In-Reply-To: a un parche +(por ejemplo, al usar ``git send-email``) para asociar el parche con una +discusión anterior relevante, por ejemplo para vincular una corrección de +errores al correo electrónico con el informe de errores. Sin embargo, para +una serie de parches múltiples, generalmente es mejor evitar usar +In-Reply-To: para vincular a versiones anteriores de la serie. De esta +forma, varias versiones del parche no se convierten en un inmanejable +bosque de referencias en clientes de correo electrónico. Si un enlace es +útil, puede usar el redirector https://lore.kernel.org/ (por ejemplo, en +el texto de la carta de introducción del correo electrónico) para vincular +a una versión anterior de la serie de parches. + + +Proporcionar información de árbol base +-------------------------------------- + +Cuando otros desarrolladores reciben sus parches y comienzan el proceso de +revisión, a menudo es útil para ellos saber en qué parte del historial del +árbol deben colocar su trabajo. Esto es particularmente útil para CI +automatizado de procesos que intentan ejecutar una serie de pruebas para +establecer la calidad de su envío antes de que el maintainer comience la +revisión. + +Si está utilizando ``git format-patch`` para generar sus parches, puede +incluir automáticamente la información del árbol base en su envío usando el +parámetro ``--base``. La forma más fácil y conveniente de usar esta opción +es con "topical branches" (ramas de temas):: + + $ git checkout -t -b my-topical-branch master + Branch 'my-topical-branch' set up to track local branch 'master'. + Switched to a new branch 'my-topical-branch' + + [realice sus cambios y ediciones] + + $ git format-patch --base=auto --cover-letter -o outgoing/ master + outgoing/0000-cover-letter.patch + outgoing/0001-First-Commit.patch + outgoing/... + +Cuando abra ``outgoing/0000-cover-letter.patch`` para editar, tenga en +cuenta que tendrá el tráiler ``base-commit:`` al final, que proporciona al +revisor y a las herramientas de CI suficiente información para realizar +correctamente ``git am`` sin preocuparse por los conflictos:: + + $ git checkout -b patch-review [base-commit-id] + Switched to a new branch 'patch-review' + $ git am patches.mbox + Applying: First Commit + Applying: ... + +Consulte ``man git-format-patch`` para obtener más información al respecto +de esta opción. + +.. Note:: + + La función ``--base`` se introdujo en la versión 2.9.0 de git. + +Si no está utilizando git para dar forma a sus parches, aún puede incluir +el mismo tráiler ``base-commit`` para indicar el hash de confirmación del +árbol en que se basa su trabajo. Debe agregarlo en la carta de presentación +o en el primer parche de la serie y debe colocarse ya sea bajo la línea +``---`` o en la parte inferior de todos los demás contenido, justo antes de +su firma del correo electrónico. + + +Referencias +----------- + +"The perfect patch" (tpp) por Andrew Morton. + <https://www.ozlabs.org/~akpm/stuff/tpp.txt> + +"Linux kernel patch submission format" por Jeff Garzik. + <https://web.archive.org/web/20180829112450/http://linux.yyz.us/patch-format.html> + +"How to piss off a kernel subsystem maintainer" por Greg Kroah-Hartman. + <http://www.kroah.com/log/linux/maintainer.html> + + <http://www.kroah.com/log/linux/maintainer-02.html> + + <http://www.kroah.com/log/linux/maintainer-03.html> + + <http://www.kroah.com/log/linux/maintainer-04.html> + + <http://www.kroah.com/log/linux/maintainer-05.html> + + <http://www.kroah.com/log/linux/maintainer-06.html> + +NO!!!! Gente, no mas bombas enormes de parches a linux-kernel@vger.kernel.org! + <https://lore.kernel.org/r/20050711.125305.08322243.davem@davemloft.net> + +Kernel Documentation/process/coding-style.rst + +Email de Linus Torvalds sobre la forma canónica de los parches: + <https://lore.kernel.org/r/Pine.LNX.4.58.0504071023190.28951@ppc970.osdl.org> + +"On submitting kernel patches" por Andi Kleen + Algunas estrategias para conseguir incluir cambios complicados o + controvertidos. + + http://halobates.de/on-submitting-patches.pdf |