Spanish

Warning

Si tiene alguna duda sobre la exactitud del contenido de esta traducción, la única referencia válida es la documentación oficial en inglés. Además, por defecto, los enlaces a documentos redirigen a la documentación en inglés, incluso si existe una versión traducida. Consulte el índice para más información.

Original:

KVM x86

Translator:

Juan Embid <jembid@ucm.es>

KVM x86

TL;DR

Las pruebas son obligatorias. Sea coherente con los estilos y patrones establecidos.

Árboles

KVM x86 se encuentra actualmente en un período de transición de ser parte del árbol principal de KVM, a ser “sólo otra rama de KVM”. Como tal, KVM x86 está dividido entre el árbol principal de KVM, git.kernel.org/pub/scm/virt/kvm/kvm.git, y un árbol específico de KVM x86, github.com/kvm-x86/linux.git.

Por lo general, las correcciones para el ciclo en curso se aplican directamente al árbol principal de KVM, mientras que todo el desarrollo para el siguiente ciclo se dirige a través del árbol de KVM x86. En el improbable caso de que una corrección para el ciclo actual se dirija a través del árbol KVM x86, se aplicará a la rama fixes antes de llegar al árbol KVM principal.

Tenga en cuenta que se espera que este periodo de transición dure bastante tiempo, es decir, que será el statu quo en un futuro previsible.

Ramas

El árbol de KVM x86 está organizado en múltiples ramas por temas. El propósito de utilizar ramas temáticas más específicas es facilitar el control de un área de desarrollo, y para limitar los daños colaterales de errores humanos y/o commits con errores, por ejemplo, borrar el commit HEAD de una rama temática no tiene impacto en los hashes SHA1 de otros commit en en camino, y tener que rechazar una solicitud de pull debido a errores retrasa sólo esa rama temática.

Todas las ramas temáticas, excepto next y fixes, se agrupan en next a través de un Cthulhu merge en función de las necesidades, es decir, cuando se actualiza una rama temática. Como resultado, los push forzados a next son comunes.

Ciclo de Vida

Las correcciones dirigidas a la versión actual, también conocida como mainline, suelen aplicarse directamente al árbol principal de KVM, es decir, no pasan por el árbol x86 de KVM.

Los cambios dirigidos a la siguiente versión se dirigen a través del árbol KVM x86. Se envían pull requests (de KVM x86 a KVM main) para cada rama temática de KVM x86, normalmente la semana antes de que Linus abra la ventana de fusión, por ejemplo, la semana siguiente a rc7 para las versiones “normales”. Si todo va bien, las ramas temáticas son subidas en el pull request principal de KVM enviado durante la ventana de fusión de Linus.

El árbol de KVM x86 no tiene su propia ventana de fusión oficial, pero hay un cierre suave alrededor de rc5 para nuevas características, y un cierre suave alrededor de rc6 para correcciones (para la próxima versión; fíjese más arriba para las correcciones dirigidas a la versión actual).

Cronología

Normalmente, los envíos se revisan y aplican en orden FIFO, con cierto margen de maniobra en función del tamaño de la serie, los parches que están “calientes en caché”, etc. Correcciones, especialmente para la versión actual y/o árboles estables, consiguen saltar la cola. Los parches que se lleven a través de un árbol que no sea KVM (la mayoría de las veces a través del árbol de consejos) y/o que tengan otros acks/revisiones también saltan la cola hasta cierto punto.

Tenga en cuenta que la mayor parte de la revisión se realiza entre rc1 y rc6, más o menos. El periodo entre la rc6 y la siguiente rc1 se utiliza para ponerse al día en otras tareas, es decir, la falta de envíos durante este periodo no es inusual.

Los pings para obtener una actualización del estado son bienvenidos, pero tenga en cuenta el calendario del ciclo de publicación actual y tenga expectativas realistas. Si está haciendo ping para la aceptación, es decir, no sólo para obtener comentarios o una actualización, por favor haga todo lo posible, dentro de lo razonable, para asegurarse de que sus parches están listos para ser fusionados. Los pings sobre series que rompen la compilación o fallan en las pruebas provocan el descontento de los mantenedores.

Desarrollo

Árbol base/Rama

Las correcciones dirigidas a la versión actual, también conocida como mainline, deben basarse en git://git.kernel.org/pub/scm/virt/kvm/kvm.git master. Tenga en cuenta que las correcciones no garantizan automáticamente la inclusión en la versión actual. No hay una regla única, pero normalmente sólo las correcciones de errores urgentes, críticos y/o introducidos en la versión actual deberían incluirse en la versión actual.

Todo lo demás debería basarse en kvm-x86/next, es decir, no hay necesidad de seleccionar una rama temática específica como base. Si hay conflictos y/o dependencias entre ramas, es trabajo del mantenedor resolverlos.

La única excepción al uso de kvm-x86/next como base es si un parche/serie es una serie multi-arquitectura, es decir, tiene modificaciones no triviales en el código común de KVM y/o tiene cambios más que superficiales en el código de otras arquitecturas. Los parches/series multi-arquitectura deberían basarse en un punto común y estable en la historia de KVM, por ejemplo, la versión candidata en la que se basa kvm-x86 next. Si no está seguro de si un parche/serie es realmente multiarquitectura, sea precavido y trátelo como multiarquitectura, es decir, utilice una base común.

Estilo del codigo

Cuando se trata de estilo, nomenclatura, patrones, etc., la coherencia es la prioridad número uno en KVM x86. Si todo lo demás falla, haga coincidir lo que ya existe.

Con algunas advertencias que se enumeran a continuación, siga las recomendaciones de los responsables del árbol de consejos Coding style notes, ya que los parches/series a menudo tocan tanto archivos x86 KVM como no KVM, es decir, llaman la atención de los mantenedores de KVM y del árbol de consejos.

El uso del abeto inverso, también conocido como árbol de Navidad inverso o árbol XMAS inverso, para las declaraciones de variables no es estrictamente necesario, aunque es preferible.

Excepto para unos pocos apuntes especiales, no utilice comentarios kernel-doc para las funciones. La gran mayoría de las funciones “públicas” de KVM no son realmente públicas, ya que están destinadas únicamente al consumo interno de KVM (hay planes para privatizar las cabeceras y exportaciones de KVM para reforzar esto).

Comentarios

Escriba los comentarios en modo imperativo y evite los pronombres. Utilice los comentarios para ofrecer una visión general de alto nivel del código y/o para explicar por qué el código hace lo que hace. No reitere lo que el código hace literalmente; deje que el código hable por sí mismo. Si el propio código es inescrutable, los comentarios no servirán de nada.

Referencias SDM y APM

Gran parte de la base de código de KVM está directamente vinculada al comportamiento de la arquitectura definido en El Manual de Desarrollo de Software (SDM) de Intel y el Manual del Programador de Arquitectura (APM) de AMD. El uso de “SDM de Intel” y “APM de AMD”, o incluso sólo “SDM” o “APM”, sin contexto adicional es correcto.

No haga referencia a secciones específicas, tablas, figuras, etc. por su número, especialmente en los comentarios. En su lugar, si es necesario (véase más abajo), copie y pegue el fragmento correspondiente y haga referencia a las secciones/tablas/figuras por su nombre. Los diseños del SDM y el APM cambian constantemente, por lo que los números/etiquetas no son estables.

En general, no haga referencia explícita ni copie-pegue del SDM o APM en los comentarios. Con pocas excepciones, KVM debe respetar el comportamiento de la arquitectura, por lo que está implícito que el comportamiento de KVM está emulando el comportamiento de SDM y/o APM. Tenga en cuenta que hacer referencia al SDM/APM en los registros de cambios para justificar el cambio y proporcionar contexto es perfectamente correcto y recomendable.

Shortlog

El formato de prefijo más recomendable es KVM: <topic>:, donde <topic> es uno de los siguientes:

- x86
- x86/mmu
- x86/pmu
- x86/xen
- autocomprobaciones
- SVM
- nSVM
- VMX
- nVMX

¡NO use x86/kvm! x86/kvm se usa exclusivamente para cambios de Linux virtualizado por KVM, es decir, para arch/x86/kernel/kvm.c. No use nombres de archivos o archivos completos como prefijo de asunto/shortlog.

Tenga en cuenta que esto no coincide con las ramas temáticas (las ramas temáticas se preocupan mucho más por los conflictos de código).

Todos los nombres distinguen entre mayúsculas y minúsculas. KVM: x86: es correcto, kvm: vmx: no lo es.

Escriba en mayúsculas la primera palabra de la descripción condensada del parche, pero omita la puntuación final. Por ejemplo:

KVM: x86: Corregir una desviación de puntero nulo en function_xyz()

no:

kvm: x86: corregir una desviación de puntero nulo en function_xyz.

Si un parche afecta a varios temas, recorra el árbol conceptual hasta encontrar el primer padre común (que suele ser simplemente x86). En caso de duda, git log path/to/file debería proporcionar una pista razonable.

De vez en cuando surgen nuevos temas, pero le rogamos que inicie un debate en la lista si desea proponer la introducción de un nuevo tema, es decir, no se ande con rodeos.

Consulte The canonical patch format para obtener más información, con una enmienda: no trate el límite de 70-75 caracteres como un límite absoluto y duro. En su lugar, utilice 75 caracteres como límite firme, pero no duro, y 80 caracteres como límite duro. Es decir, deje que el registro corto sobrepase en algunos caracteres el límite estándar si tiene una buena razón para hacerlo.

Registro de cambios

Y lo que es más importante, escriba los registros de cambios en modo imperativo y evite los pronombres.

Consulte Describe your changes para obtener más información, con una recomendación: comience con un breve resumen de los cambios reales y continúe con el contexto y los antecedentes. Nota. Este orden entra en conflicto directo con el enfoque preferido del árbol de sugerencias. Por favor, siga el estilo preferido del árbol de sugerencias cuando envíe parches. que se dirigen principalmente a código arch/x86 que _NO_ es código KVM.

KVM x86 prefiere indicar lo que hace un parche antes de entrar en detalles por varias razones. En primer lugar, el código que realmente se está cambiando es posiblemente la información más importante, por lo que esa información debe ser fácil de encontrar. Changelogs que entierran el “qué está cambiando realmente” en una sola línea después de 3+ párrafos de fondo hacen muy difícil encontrar esa información.

Para la revisión inicial, se podría argumentar que “lo que está roto” es más importante, pero para hojear los registros y la arqueología git, los detalles escabrosos importan cada vez menos. Por ejemplo, al hacer una serie de “git blame”, los detalles de cada cambio a lo largo del camino son inútiles, los detalles sólo importan para el culpable. Proporcionar el “qué ha cambiado” facilita determinar rápidamente si una confirmación puede ser de interés o no.

Otra ventaja de decir primero “qué cambia” es que casi siempre es posible decir “qué cambia” en una sola frase. A la inversa, todo menos los errores más simples requieren varias frases o párrafos para describir el problema. Si tanto “qué está cambiando” como “cuál es el fallo” son muy breves, el orden no importa. Pero si uno es más corto (casi siempre el “qué está cambiando”), entonces cubrir el más corto primero es ventajoso porque es menos inconveniente para los lectores/revisores que tienen una preferencia estricta de orden. Por ejemplo, tener que saltarse una frase para llegar al contexto es menos doloroso que tener que saltarse tres párrafos para llegar a “lo que cambia”.

Arreglos

Si un cambio corrige un error de KVM/kernel, añada una etiqueta Fixes: incluso si el cambio no necesita ser retroportado a kernels estables, e incluso si el cambio corrige un error en una versión anterior.

Por el contrario, si es necesario hacer una corrección, etiquete explícitamente el parche con “Cc: stable@vger.kernel” (aunque no es necesario que el correo electrónico incluya Cc: stable); KVM x86 opta por excluirse del backporting Correcciones: por defecto. Algunos parches seleccionados automáticamente se retroportan, pero requieren la aprobación explícita de los mantenedores (busque MANUALSEL).

Referencias a Funciones

Cuando se mencione una función en un comentario, registro de cambios o registro abreviado (o en cualquier otro lugar), utilice el formato nombre_de_la_función(). Los paréntesis proporcionan contexto y desambiguan la referencia.

Pruebas

Como mínimo, todos los parches de una serie deben construirse limpiamente para KVM_INTEL=m KVM_AMD=m, y KVM_WERROR=y. Construir todas las combinaciones posibles de Kconfigs no es factible, pero cuantas más mejor. KVM_SMM, KVM_XEN, PROVE_LOCKING, y X86_64 son particularmente interesantes.

También es obligatorio ejecutar las autopruebas y las pruebas unitarias de KVM (y, como es obvio, las pruebas deben pasar). La única excepción es para los cambios que tienen una probabilidad insignificante de afectar al comportamiento en tiempo de ejecución, por ejemplo, parches que sólo modificar los comentarios. Siempre que sea posible y pertinente, se recomienda encarecidamente realizar pruebas tanto en Intel como en AMD. Se recomienda arrancar una máquina virtual real, pero no es obligatorio.

Para cambios que afecten al código de paginación en la sombra de KVM, es obligatorio ejecutar con TDP (EPT/NPT) deshabilitado. Para cambios que afecten al código MMU común de KVM, se recomienda encarecidamente ejecutar con TDP deshabilitado. Para todos los demás cambios, si el código que se está modificando depende de y/o interactúa con un parámetro del módulo, es obligatorio realizar pruebas con la configuración correspondiente.

Tenga en cuenta que las autopruebas de KVM y las pruebas de unidad de KVM tienen fallos conocidos. Si sospecha que un fallo no se debe a sus cambios, verifique que el exactamente el mismo fallo se produce con y sin sus cambios.

Los cambios que afecten a la documentación de texto reestructurado, es decir, a los archivos .rst, deben generar htmldocs de forma limpia, es decir, sin advertencias ni errores.

Si no puede probar completamente un cambio, por ejemplo, por falta de hardware, indique claramente qué nivel de pruebas ha podido realizar, por ejemplo, en la carta de presentación.

Novedades

Con una excepción, las nuevas características deben venir con cobertura de pruebas. Las pruebas específicas de KVM no son estrictamente necesarias, por ejemplo, si la cobertura se proporciona mediante la ejecución de una prueba de VM huésped suficientemente habilitada, o ejecutando una autoprueba de kernel relacionada en una VM, pero en todos los casos se prefieren las pruebas KVM dedicadas. Los casos de prueba negativos en particular son obligatorios para la habilitación de nuevas características de hardware, ya que los flujos de errores y excepciones rara vez se ejercitan simplemente ejecutando una VM.

La única excepción a esta regla es si KVM está simplemente anunciando soporte para un a través de KVM_GET_SUPPORTED_CPUID, es decir, para instrucciones/funciones que KVM no puede impedir que utilice una VM y para las que no existe una verdadera habilitación.

Tenga en cuenta que “nuevas características” no significa sólo “nuevas características de hardware”. Las nuevas funcionalidades que no puedan ser validadas usando las pruebas existentes de KVM y/o las pruebas unitarias de KVM deben venir con pruebas.

Es más que bienvenido el envío de nuevos desarrollos de características sin pruebas para obtener un feedback temprano, pero tales envíos deben ser etiquetados como RFC, y la carta de presentación debe indicar claramente qué tipo de feedback se solicita/espera. No abuse del proceso de RFC; las RFC no suelen recibir una revisión en profundidad.

Corrección de Errores

Salvo en el caso de fallos “obvios” detectados por inspección, las correcciones deben ir acompañadas de un reproductor del fallo corregido. En muchos casos, el reproductor está implícito, por ejemplo, para errores de compilación y fallos de prueba, pero debe quedar claro para lectores qué es lo que no funciona y cómo verificar la solución. Se concede cierto margen a los errores detectados mediante cargas de trabajo/pruebas no públicas, pero se recomienda encarecidamente que se faciliten pruebas de regresión para dichos errores.

En general, las pruebas de regresión son preferibles para cualquier fallo que no sea trivial de encontrar. Por ejemplo, incluso si el error fue encontrado originalmente por un fuzzer como syzkaller, una prueba de regresión dirigida puede estar justificada si el error requiere golpear una condición de carrera de tipo uno en un millón.

Recuerde que los fallos de KVM rara vez son urgentes y no triviales de reproducir. Pregúntate si un fallo es realmente el fin del mundo antes de publicar una corrección sin un reproductor.

Publicación

Enlaces

No haga referencia explícita a informes de errores, versiones anteriores de un parche/serie, etc. mediante cabeceras In-Reply-To:. Usar In-Reply-To: se convierte en un lío para grandes series y/o cuando el número de versiones es alto, y In-Reply-To: es inútil para cualquiera que no tenga el mensaje original, por ejemplo, si alguien no recibió un Cc en el informe de error o si la lista de destinatarios cambia entre versiones.

Para enlazar con un informe de error, una versión anterior o cualquier cosa de interés, utiliza enlaces lore. Para hacer referencia a versiones anteriores, en general no incluya un Enlace: en el registro de cambios, ya que no hay necesidad de registrar la historia en git, es decir, ponga el enlace en la carta de presentación o en la sección que git ignora. Proporcione un Enlace: formal para los informes de errores y/o discusiones que condujeron al parche. El contexto de por qué se hizo un cambio es muy valioso para futuros lectores.

Basado en Git

Si utilizas la versión 2.9.0 o posterior de git (Googlers, ¡os incluimos a todos!), utilice git format-patch con el indicador --base para incluir automáticamente la información del árbol base en los parches generados.

Tenga en cuenta que --base=auto funciona como se espera si y sólo si el upstream de una rama se establece en la rama temática base, por ejemplo, hará lo incorrecto si su upstream se establece en su repositorio personal con fines de copia de seguridad. Una solución “automática” alternativa es derivar los nombres de tus ramas de desarrollo basándose en su KVM x86, e introdúzcalo en --base. Por ejemplo, x86/pmu/mi_nombre_de_rama, y luego escribir un pequeño wrapper para extraer pmu del nombre de la rama actual para obtener --base=x/pmu, donde x es el nombre que su repositorio utiliza para rastrear el remoto KVM x86.

Tests de Co-Publicación

Las autopruebas de KVM asociadas a cambios de KVM, por ejemplo, pruebas de regresión para correcciones de errores, deben publicarse junto con los cambios de KVM como una única serie. Se aplicarán las reglas estándar del núcleo para la bisección, es decir, los cambios de KVM que provoquen fallos en las pruebas se ordenarán después de las actualizaciones de las autopruebas, y viceversa. Las pruebas que fallan debido a errores de KVM deben ordenarse después de las correcciones de KVM.

KVM-unit-tests debería siempre publicarse por separado. Las herramientas, por ejemplo b4 am, no saben que KVM-unit-tests es un repositorio separado y se confunden cuando los parches de una serie se aplican en diferentes árboles. Para vincular los parches de KVM-unit-tests a Parches KVM, primero publique los cambios KVM y luego proporcione un enlace lore Link: al parche/serie KVM en el parche(s) KVM-unit-tests.

Notificaciones

Cuando se acepte oficialmente un parche/serie, se enviará un correo electrónico de notificación en respuesta a la publicación original (carta de presentación para series de varios parches). La notificación incluirá el árbol y la rama temática, junto con los SHA1 de los commits de los parches aplicados.

Si se aplica un subconjunto de parches, se indicará claramente en la notificación. A menos que se indique lo contrario, se sobreentiende que todos los parches del Las series que no han sido aceptadas necesitan más trabajo y deben presentarse en una nueva versión.

Si por alguna razón se retira un parche después de haber sido aceptado oficialmente, se enviará una respuesta al correo electrónico de notificación explicando por qué se ha retirado el parche, así como los pasos siguientes.

Estabilidad SHA1

Los SHA1 no son 100% estables hasta que llegan al árbol de Linus. Un SHA1 es normalmente estable una vez que se ha enviado una notificación, pero ocurren cosas. En la mayoría de los casos, se proporcionará una actualización del correo electrónico de notificación si se aplica un SHA1 del parche. Sin embargo, en algunos escenarios, por ejemplo, si todas las ramas de KVM x86 necesitan ser rebasadas, no se darán notificaciones individuales.

Vulnerabilidades

Los fallos que pueden ser explotados por la VM (el “guest”) para atacar al host (kernel o espacio de usuario), o que pueden ser explotados por una VM anidada a su host (L2 atacando a L1), son de particular interés para KVM. Por favor, siga el protocolo para Security bugs si sospecha que un fallo puede provocar una filtración de datos, etc.