Lines Matching +full:un +full:-
1 .. include:: ../disclaimer-sp.rst
3 :Original: :ref:`Documentation/process/adding-syscalls.rst <addsyscalls>`
13 :ref:`Documentation/process/submitting-patches.rst <submittingpatches>` que
17 -----------------------------------
22 tradicionales, existen otras posibilidades -- elija la que mejor se adecúe
25 - Si se puede hacer que la operación se parezca a un objeto filesystem,
26 podría tener más sentido crear un nuevo sistema de ficheros o
28 funcionalidad en un módulo del kernel en vez de requerir que sea
31 - Si la nueva funcionalidad involucra operaciones donde el kernel
32 notifica al userspace que algo ha pasado, entonces retornar un nuevo
36 - Sin embargo, operaciones que no mapean a operaciones similares a
38 como solicitudes :manpage:`ioctl(2)`, las cuales pueden llevar a un
41 - Si sólo está exponiendo información del runtime, un nuevo nodo en sysfs
45 siempre el caso (e.g. en un ambiente namespaced/sandboxed/chrooted).
49 - Si la operación es específica a un archivo o descriptor de archivo
55 es muy simple (por ejemplo, definir/obtener un flag simple relacionado a
56 un descriptor de archivo).
58 - Si la operación es específica a un proceso o tarea particular, entonces
59 un comando adicional :manpage:`prctl(2)` podría ser más apropiado. Tal
60 como con :manpage:`fcntl(2)`, esta llamada al sistema es un multiplexor
62 del existente ``prctl()`` u obtener/definir un flag simple relacionado a
63 un proceso.
66 --------------------------------------------
74 hizo, junto con los correspondientes seguimientos de los system calls --
76 ``pipe``/``pipe2``, ``renameat``/``renameat2`` -- así que aprenda de la
79 Para llamadas al sistema más simples que sólo toman un par de argumentos,
80 la forma preferida de permitir futuras extensiones es incluir un argumento
87 return -EINVAL;
92 Para llamadas al sistema más sofisticadas que involucran un gran número de
94 estructura que sea pasada a través de un puntero. Tal estructura puede
95 hacer frente a futuras extensiones mediante la inclusión de un argumento de
99 u32 size; /* userspace define p->size = sizeof(struct xyzzy_params) */
106 diseñado de forma tal que un valor cero, devuelva el comportamiento previo,
109 - Para hacer frente a programas del userspace más modernos, haciendo
110 llamadas a un kernel más antiguo, el código del kernel debe revisar que
113 - Para hacer frente a programas antiguos del userspace haciendo llamadas a
114 un kernel más nuevo, el código del kernel puede extender con ceros, una
119 ``kernel/events/code.c``) para un ejemplo de esta aproximación.
123 ---------------------------------------
125 Si su nueva llamada al sistema permite al userspace hacer referencia a un
126 objeto del kernel, esta debería usar un descriptor de archivo como el
127 manipulador de ese objeto -- no invente un nuevo tipo de objeto manipulador
131 Si su nueva llamada a sistema :manpage:`xyzzy(2)` retorna un nuevo
132 descriptor de archivo, entonces el argumento flag debe incluir un valor que
135 ``fcntl(fd, F_SETFD, FD_CLOEXEC)``, donde un ``fork()`` inesperado y
136 ``execve()`` en otro hilo podrían filtrar un descriptor al programa
139 parte de un espacio numerado de flags ``O_*`` que está bastante lleno.)
141 Si su llamada de sistema retorna un nuevo descriptor de archivo, debería
143 :manpage:`poll(2)` en ese descriptor de archivo. Hacer un descriptor de
145 indique al espacio de usuario que un evento ha ocurrido en el
160 un descriptor de archivo ya abierto usando el flag ``AT_EMPTY_PATH``,
163 - xyzzyat(AT_FDCWD, path, ..., 0) es equivalente a xyzzy(path, ...)
164 - xyzzyat(fd, "", ..., AT_EMPTY_PATH) es equivalente a fxyzzy(fd, ...)
167 revise el man page :manpage:`openat(2)`; para un ejemplo de AT_EMPTY_PATH,
170 Si su nueva llamada de sistema :manpage:`xyzzy(2)` involucra un parámetro
171 describiendo un describiendo un movimiento dentro de un archivo, ponga de
172 tipo ``loff_t`` para que movimientos de 64-bit puedan ser soportados
173 incluso en arquitecturas de 32-bit.
185 Si su nueva llamada de sistema :manpage:`xyzzy(2)` manipula un proceso que
191 Finalmente, debe ser conciente de que algunas arquitecturas no-x86 tienen
192 un manejo más sencillo si los parámetros que son explícitamente 64-bit
194 permitir el uso de pares contiguos de registros 32-bits. (Este cuidado no
196 un puntero.)
199 ------------------
206 - La implementación central de la llamada al sistema, junto con
209 - Conectar la nueva llamada a sistema a una arquitectura particular,
211 - Una demostración del use de la nueva llamada a sistema en el userspace
212 vía un selftest en ``tools/testing/selftest/``.
213 - Un borrador de man-page para la nueva llamada a sistema, ya sea como
214 texto plano en la carta de presentación, o como un parche (separado)
215 para el repositorio man-pages.
218 kernel, debería siempre ser copiado a linux-api@vger.kernel.org.
222 ---------------------------------------------
232 El nuevo punto de entrada también necesita un prototipo de función
242 ``include/uapi/asm-generic/unistd.h``::
253 (rutina de respaldo) para cada llamada de sistema, retornando ``-ENOSYS``.
263 - Incluya una descripción para la nueva funcionalidad y llamada al sistema
265 - Haga la opción dependiendo de EXPERT si esta debe estar escondida de los
267 - Haga que cualquier nuevo archivo fuente que implemente la función
269 ``obj-$(CONFIG_XYZZY_SYSCALL) += xyzzy.o``).
270 - Revise dos veces que el kernel se siga compilando con la nueva opción
273 Para resumir, necesita un commit que incluya:
275 - una opción ``CONFIG`` para la nueva función, normalmente en ``init/Kconfig``
276 - ``SYSCALL_DEFINEn(xyzzy, ...)`` para el punto de entrada
277 - El correspondiente prototipo en ``include/linux/syscalls.h``
278 - Una entrada genérica en ``include/uapi/asm-generic/unistd.h``
279 - fallback stub en ``kernel/sys_ni.c``
283 ----------------------------------------
302 ------------------------------------------------
304 Para la mayoría de llamadas al sistema la misma implementación 64-bit puede
305 ser invocada incluso cuando el programa de userspace es en si mismo 32-bit;
306 incluso si los parámetros de la llamada de sistema incluyen un puntero
309 Sin embargo, existe un par de situaciones donde se necesita una capa de
310 compatibilidad para lidiar con las diferencias de tamaño entre 32-bit y
311 64-bit.
313 La primera es si el kernel 64-bit también soporta programas del userspace
314 32-bit, y por lo tanto necesita analizar areas de memoria del (``__user``)
315 que podrían tener valores tanto 32-bit como 64-bit. En particular esto se
316 necesita siempre que un argumento de la llamada a sistema es:
318 - un puntero a un puntero
319 - un puntero a un struc conteniendo un puntero (por ejemplo
321 - un puntero a un type entero de tamaño entero variable (``time_t``,
323 - un puntero a un struct conteniendo un type entero de tamaño variable.
326 de los argumentos de la llamada a sistema tiene un argumento que es
327 explícitamente 64-bit incluso sobre arquitectura 32-bit, por ejemplo
328 ``loff_t`` o ``__u64``. En este caso, el valor que llega a un kernel 64-bit
329 desde una aplicación de 32-bit se separará en dos valores de 32-bit, los
332 (Note que un argumento de una llamada a sistema que sea un puntero a un
333 type explicitamente de 64-bit **no** necesita una capa de compatibilidad;
341 versión de la implementación se ejecuta como parte de un kernel de 64-bit,
342 pero espera recibir parametros con valores 32-bit y hace lo que tenga que
347 El punto de entrada compat también necesita un prototipo de función
354 de forma distinta en sistema de 32-bit y 64-bit, digamos
361 de 32-bit.
383 ``include/uapi/asm-generic/unistd.h`` debería usar ``__SC_COMP`` en vez de
391 - una ``COMPAT_SYSCALL_DEFINEn(xyzzy, ...)`` para el punto de entrada de compat.
392 - el prototipo correspondiente en ``include/linux/compat.h``
393 - (en caso de ser necesario) un struct de mapeo de 32-bit en ``include/linux/compat.h``
394 - una instancia de ``__SC_COMP`` no ``__SYSCALL`` en ``include/uapi/asm-generic/unistd.h``
397 -------------------------------------------
404 una columna extra para indicar que un programa del userspace de 32-bit
405 corriendo en un kernel de 64-bit debe llegar al punto de entrada compat::
411 argumentos debería coincidir con la versión de 64-bit o la versión de
412 32-bit.
414 Si hay involucrado un puntero-a-puntero, la decisión es fácil: x32 es
415 ILP32, por lo que el diseño debe coincidir con la versión 32-bit, y la
417 progamas 32-bit lleguen al envoltorio de compatibilidad::
424 call 64-bit para el x32 ABI (y consecuentemente la entrada en
428 argumentos de hecho asigne exactamente de x32 (-mx32) a 32-bit(-m32) o
429 equivalentes 64-bit (-m64).
433 ----------------------------------------------
437 quedó -- en la siguiente instrucción, con el stack igual y la mayoría de
451 Esto es arch-specific, pero típicamente involucra definir puntos de entrada
455 Para x86_64, esto es implementado como un punto de entrada ``stub_xyzzy``
461 El equivalente para programas 32-bit corriendo en un kernel 64-bit es
471 nativa de 64-bit. También, si la implementación de la versión x32 ABI no es
473 invocar un stub que llame a la versión ``compat_sys_``
475 Para completar, también es agradable configurar un mapeo de modo que el
476 user-mode linux todavía funcione -- su tabla syscall referenciará
478 ``arch/x86/entry/entry_64.S``. Arreglar esto es tan simple como agregar un
485 --------------
491 El subsistema de auditoría es un caso especial; este incluye funciones
492 (arch-specific) que clasifican algunos tipos especiales de llamadas al
493 sistema -- específicamente file open (``open``/``openat``), program
499 nueva llamada al sistema, entonces vale la pena hacer un grep a todo el
505 -------
510 objetivos es incluir un simple programa self-test en un nuevo directorio
516 estructura userspace-visible, el encabezado correspondiente necesitará ser
520 soportadas. Por ejemplo, revise si funciona cuando es compilado como un
521 x86_64 (-m64), x86_32 (-m32) y x32 (-mx32) programa ABI.
525 xfstests para cambios filesystem-related
527 - https://linux-test-project.github.io/
528 - git://git.kernel.org/pub/scm/fs/xfs/xfstests-dev.git
532 --------
534 Todas las llamada al sistema nueva deben venir con un man page completo,
536 usa groff, es útil incluir una versión ASCII pre-renderizada del man-page
540 El man page debe ser cc'do a linux-man@vger.kernel.org
541 Para más detalles, revise https://www.kernel.org/doc/man-pages/patches.html
545 ------------------------------------------------
559 Al menos en 64-bit x86, será un requerimiento duro desde la v4.17 en
562 sistema donde ``struct pt_regs`` es decodificado on-the-fly en un
580 ---------------------
582 - Artículo LWN de Michael Kerrisk sobre el uso de argumentos flags en llamadas al
585 - Artículo LWN de Michael Kerrisk sobre cómo manejar flags desconocidos en una
587 - Artículo LWN de Jake Edge describiendo restricciones en argumentos en
588 64-bit system call: https://lwn.net/Articles/311630/
589 - Par de artículos LWN de David Drysdale que describen la ruta de implementación
592 - https://lwn.net/Articles/604287/
593 - https://lwn.net/Articles/604515/
595 - Requerimientos arquitectura-específicos para llamadas al sistema son discutidos en el
596 :manpage:`syscall(2)` man-page:
597 http://man7.org/linux/man-pages/man2/syscall.2.html#NOTES
598 - Recopilación de emails de Linus Torvalds discutiendo problemas con ``ioctl()``:
600 - "How to not invent kernel interfaces", Arnd Bergmann,
602 - Artículo LWN de Michael Kerrisk sobre evitar nuevos usos de CAP_SYS_ADMIN:
604 - Recomendaciones de Andrew Morton que toda la información relacionada a una nueva
606 https://lore.kernel.org/r/20140724144747.3041b208832bbdf9fbce5d96@linux-foundation.org
607 - Recomendaciones de Michael Kerrisk que una nueva llamada al sistema debe venir
608 …con un man-page: https://lore.kernel.org/r/CAKgNAkgMA39AfoSoA5Pe1r9N+ZzfYQNvNPvcRN7tOvRb8+v06Q@mai…
609 - Sugerencias de Thomas Gleixner que conexiones x86 deben ir en commits
611 - Sugerencias de Greg Kroah-Hartman que es bueno para las nueva llamadas al sistema
612 que vengan con man-page y selftest: https://lore.kernel.org/r/20140320025530.GA25469@kroah.com
613 - Discusión de Michael Kerrisk de nuevas system call vs. extensiones :manpage:`prctl(2)`:
614 https://lore.kernel.org/r/CAHO5Pa3F2MjfTtfNxa8LbnkeeU8=YJ+9tDqxZpw7Gz59E-4AUg@mail.gmail.com
615 - Sugerencias de Ingo Molnar que llamadas al sistema que involucran múltiples
617 …un campo de tamaño para futura extensibilidad: https://lore.kernel.org/r/20150730083831.GA22182@gm…
618 - Enumerando rarezas por la (re-)utilización de O_* numbering space flags:
620 - commit 75069f2b5bfb ("vfs: renumber FMODE_NONOTIFY and add to uniqueness
622 - commit 12ed2e36c98a ("fanotify: FMODE_NONOTIFY and __O_SYNC in sparc
624 - commit bb458c644a59 ("Safer ABI for O_TMPFILE")
626 - Discusión de Matthew Wilcox sobre las restricciones en argumentos 64-bit:
627 https://lore.kernel.org/r/20081212152929.GM26095@parisc-linux.org
628 - Recomendaciones de Greg Kroah-Hartman sobre flags desconocidos deben ser
630 - Recomendaciones de Linus Torvalds que las llamadas al sistema x32 deben favorecer
631 compatibilidad con versiones 64-bit sobre versiones 32-bit: