|
|
|
|
@ -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
|
Linus Torvalds