466 lines · plain
1.. include:: ../disclaimer-sp.rst2 3:Original: Documentation/process/maintainer-kvm-x86.rst4:Translator: Juan Embid <jembid@ucm.es>5 6KVM x867=======8 9Prólogo10--------11KVM se esfuerza por ser una comunidad acogedora; las contribuciones de los12recién llegados son valoradas e incentivadas. Por favor, no se desanime ni13se sienta intimidado por la extensión de este documento y las numerosas14normas/directrices que contiene. Todos cometemos errores y todos hemos sido15principiantes en algún momento. Mientras haga un esfuerzo honesto por16seguir las directrices de KVM x86, sea receptivo a los comentarios, y17aprenda de los errores que cometa, será recibido con los brazos abiertos,18no con antorchas y horcas.19 20TL;DR21-----22Las pruebas son obligatorias. Sea coherente con los estilos y patrones23establecidos.24 25Árboles26-------27KVM x86 se encuentra actualmente en un período de transición de ser parte28del árbol principal de KVM, a ser "sólo otra rama de KVM". Como tal, KVM29x86 está dividido entre el árbol principal de KVM,30``git.kernel.org/pub/scm/virt/kvm/kvm.git``, y un árbol específico de KVM31x86, ``github.com/kvm-x86/linux.git``.32 33Por lo general, las correcciones para el ciclo en curso se aplican34directamente al árbol principal de KVM, mientras que todo el desarrollo35para el siguiente ciclo se dirige a través del árbol de KVM x86. En el36improbable caso de que una corrección para el ciclo actual se dirija a37través del árbol KVM x86, se aplicará a la rama ``fixes`` antes de llegar38al árbol KVM principal.39 40Tenga en cuenta que se espera que este periodo de transición dure bastante41tiempo, es decir, que será el statu quo en un futuro previsible.42 43Ramas44~~~~~45El árbol de KVM x86 está organizado en múltiples ramas por temas. El46propósito de utilizar ramas temáticas más específicas es facilitar el47control de un área de desarrollo, y para limitar los daños colaterales de48errores humanos y/o commits con errores, por ejemplo, borrar el commit HEAD49de una rama temática no tiene impacto en los hashes SHA1 de otros commit50en en camino, y tener que rechazar una solicitud de pull debido a errores51retrasa sólo esa rama temática.52 53Todas las ramas temáticas, excepto ``next`` y ``fixes``, se agrupan en54``next`` a través de un Cthulhu merge en función de las necesidades, es55decir, cuando se actualiza una rama temática. Como resultado, los push56forzados a ``next`` son comunes.57 58Ciclo de Vida59~~~~~~~~~~~~~60Las correcciones dirigidas a la versión actual, también conocida como61mainline, suelen aplicarse directamente al árbol principal de KVM, es62decir, no pasan por el árbol x86 de KVM.63 64Los cambios dirigidos a la siguiente versión se dirigen a través del árbol65KVM x86. Se envían pull requests (de KVM x86 a KVM main) para cada rama66temática de KVM x86, normalmente la semana antes de que Linus abra la67ventana de fusión, por ejemplo, la semana siguiente a rc7 para las68versiones "normales". Si todo va bien, las ramas temáticas son subidas en69el pull request principal de KVM enviado durante la ventana de fusión de70Linus.71 72El árbol de KVM x86 no tiene su propia ventana de fusión oficial, pero hay73un cierre suave alrededor de rc5 para nuevas características, y un cierre74suave alrededor de rc6 para correcciones (para la próxima versión; fíjese75más arriba para las correcciones dirigidas a la versión actual).76 77Cronología78~~~~~~~~~~79Normalmente, los envíos se revisan y aplican en orden FIFO, con cierto80margen de maniobra en función del tamaño de la serie, los parches que están81"calientes en caché", etc. Correcciones, especialmente para la versión82actual y/o árboles estables, consiguen saltar la cola. Los parches que se83lleven a través de un árbol que no sea KVM (la mayoría de las veces a84través del árbol de consejos) y/o que tengan otros acks/revisiones también85saltan la cola hasta cierto punto.86 87Tenga en cuenta que la mayor parte de la revisión se realiza entre rc1 y88rc6, más o menos. El periodo entre la rc6 y la siguiente rc1 se utiliza89para ponerse al día en otras tareas, es decir, la falta de envíos durante90este periodo no es inusual.91 92Los pings para obtener una actualización del estado son bienvenidos, pero93tenga en cuenta el calendario del ciclo de publicación actual y tenga94expectativas realistas. Si está haciendo ping para la aceptación, es decir,95no sólo para obtener comentarios o una actualización, por favor haga todo96lo posible, dentro de lo razonable, para asegurarse de que sus parches97están listos para ser fusionados. Los pings sobre series que rompen la98compilación o fallan en las pruebas provocan el descontento de los99mantenedores.100 101Desarrollo102-----------103 104Árbol base/Rama105~~~~~~~~~~~~~~~106Las correcciones dirigidas a la versión actual, también conocida como107mainline, deben basarse en108``git://git.kernel.org/pub/scm/virt/kvm/kvm.git master``. Tenga en cuenta109que las correcciones no garantizan automáticamente la inclusión en la110versión actual. No hay una regla única, pero normalmente sólo las111correcciones de errores urgentes, críticos y/o introducidos en la versión112actual deberían incluirse en la versión actual.113 114Todo lo demás debería basarse en ``kvm-x86/next``, es decir, no hay115necesidad de seleccionar una rama temática específica como base. Si hay116conflictos y/o dependencias entre ramas, es trabajo del mantenedor117resolverlos.118 119La única excepción al uso de ``kvm-x86/next`` como base es si un120parche/serie es una serie multi-arquitectura, es decir, tiene121modificaciones no triviales en el código común de KVM y/o tiene cambios más122que superficiales en el código de otras arquitecturas. Los parches/series123multi-arquitectura deberían basarse en un punto común y estable en la124historia de KVM, por ejemplo, la versión candidata en la que se basa125``kvm-x86 next``. Si no está seguro de si un parche/serie es realmente126multiarquitectura, sea precavido y trátelo como multiarquitectura, es127decir, utilice una base común.128 129Estilo del codigo130~~~~~~~~~~~~~~~~~~~~~~131Cuando se trata de estilo, nomenclatura, patrones, etc., la coherencia es132la prioridad número uno en KVM x86. Si todo lo demás falla, haga coincidir133lo que ya existe.134 135Con algunas advertencias que se enumeran a continuación, siga las136recomendaciones de los responsables del árbol de consejos137:ref:`maintainer-tip-coding-style`, ya que los parches/series a menudo138tocan tanto archivos x86 KVM como no KVM, es decir, llaman la atención de139los mantenedores de KVM *y* del árbol de consejos.140 141El uso del abeto inverso, también conocido como árbol de Navidad inverso o142árbol XMAS inverso, para las declaraciones de variables no es estrictamente143necesario, aunque es preferible.144 145Excepto para unos pocos apuntes especiales, no utilice comentarios146kernel-doc para las funciones. La gran mayoría de las funciones "públicas"147de KVM no son realmente públicas, ya que están destinadas únicamente al148consumo interno de KVM (hay planes para privatizar las cabeceras y149exportaciones de KVM para reforzar esto).150 151Comentarios152~~~~~~~~~~~153Escriba los comentarios en modo imperativo y evite los pronombres. Utilice154los comentarios para ofrecer una visión general de alto nivel del código155y/o para explicar por qué el código hace lo que hace. No reitere lo que el156código hace literalmente; deje que el código hable por sí mismo. Si el157propio código es inescrutable, los comentarios no servirán de nada.158 159Referencias SDM y APM160~~~~~~~~~~~~~~~~~~~~~~161Gran parte de la base de código de KVM está directamente vinculada al162comportamiento de la arquitectura definido en El Manual de Desarrollo de163Software (SDM) de Intel y el Manual del Programador de Arquitectura (APM)164de AMD. El uso de "SDM de Intel" y "APM de AMD", o incluso sólo "SDM" o165"APM", sin contexto adicional es correcto.166 167No haga referencia a secciones específicas, tablas, figuras, etc. por su168número, especialmente en los comentarios. En su lugar, si es necesario169(véase más abajo), copie y pegue el fragmento correspondiente y haga170referencia a las secciones/tablas/figuras por su nombre. Los diseños del171SDM y el APM cambian constantemente, por lo que los números/etiquetas no172son estables.173 174En general, no haga referencia explícita ni copie-pegue del SDM o APM en175los comentarios. Con pocas excepciones, KVM *debe* respetar el176comportamiento de la arquitectura, por lo que está implícito que el177comportamiento de KVM está emulando el comportamiento de SDM y/o APM. Tenga178en cuenta que hacer referencia al SDM/APM en los registros de cambios para179justificar el cambio y proporcionar contexto es perfectamente correcto y180recomendable.181 182Shortlog183~~~~~~~~184El formato de prefijo más recomendable es ``KVM: <topic>:``, donde185``<topic>`` es uno de los siguientes::186 187- x86188- x86/mmu189- x86/pmu190- x86/xen191- autocomprobaciones192- SVM193- nSVM194- VMX195- nVMX196 197**¡NO use x86/kvm!** ``x86/kvm`` se usa exclusivamente para cambios de198Linux virtualizado por KVM, es decir, para arch/x86/kernel/kvm.c. No use199nombres de archivos o archivos completos como prefijo de asunto/shortlog.200 201Tenga en cuenta que esto no coincide con las ramas temáticas (las ramas202temáticas se preocupan mucho más por los conflictos de código).203 204Todos los nombres distinguen entre mayúsculas y minúsculas. ``KVM: x86:``205es correcto, ``kvm: vmx:`` no lo es.206 207Escriba en mayúsculas la primera palabra de la descripción condensada del208parche, pero omita la puntuación final. Por ejemplo::209 210 KVM: x86: Corregir una desviación de puntero nulo en function_xyz()211 212no::213 214 kvm: x86: corregir una desviación de puntero nulo en function_xyz.215 216Si un parche afecta a varios temas, recorra el árbol conceptual hasta217encontrar el primer padre común (que suele ser simplemente ``x86``). En218caso de duda, ``git log path/to/file`` debería proporcionar una pista219razonable.220 221De vez en cuando surgen nuevos temas, pero le rogamos que inicie un debate222en la lista si desea proponer la introducción de un nuevo tema, es decir,223no se ande con rodeos.224 225Consulte :ref:`the_canonical_patch_format` para obtener más información,226con una enmienda: no trate el límite de 70-75 caracteres como un límite227absoluto y duro. En su lugar, utilice 75 caracteres como límite firme, pero228no duro, y 80 caracteres como límite duro. Es decir, deje que el registro229corto sobrepase en algunos caracteres el límite estándar si tiene una buena230razón para hacerlo.231 232Registro de cambios233~~~~~~~~~~~~~~~~~~~234Y lo que es más importante, escriba los registros de cambios en modo235imperativo y evite los pronombres.236 237Consulte :ref:`describe_changes` para obtener más información, con una238recomendación: comience con un breve resumen de los cambios reales y239continúe con el contexto y los antecedentes. Nota. Este orden entra en240conflicto directo con el enfoque preferido del árbol de sugerencias. Por241favor, siga el estilo preferido del árbol de sugerencias cuando envíe242parches. que se dirigen principalmente a código arch/x86 que _NO_ es código243KVM.244 245KVM x86 prefiere indicar lo que hace un parche antes de entrar en detalles246por varias razones. En primer lugar, el código que realmente se está247cambiando es posiblemente la información más importante, por lo que esa248información debe ser fácil de encontrar. Changelogs que entierran el "qué249está cambiando realmente" en una sola línea después de 3+ párrafos de fondo250hacen muy difícil encontrar esa información.251 252Para la revisión inicial, se podría argumentar que "lo que está roto" es253más importante, pero para hojear los registros y la arqueología git, los254detalles escabrosos importan cada vez menos. Por ejemplo, al hacer una255serie de "git blame", los detalles de cada cambio a lo largo del camino son256inútiles, los detalles sólo importan para el culpable. Proporcionar el "qué257ha cambiado" facilita determinar rápidamente si una confirmación puede ser258de interés o no.259 260Otra ventaja de decir primero "qué cambia" es que casi siempre es posible261decir "qué cambia" en una sola frase. A la inversa, todo menos los errores262más simples requieren varias frases o párrafos para describir el problema.263Si tanto "qué está cambiando" como "cuál es el fallo" son muy breves, el264orden no importa. Pero si uno es más corto (casi siempre el "qué está265cambiando"), entonces cubrir el más corto primero es ventajoso porque es266menos inconveniente para los lectores/revisores que tienen una preferencia267estricta de orden. Por ejemplo, tener que saltarse una frase para llegar al268contexto es menos doloroso que tener que saltarse tres párrafos para llegar269a "lo que cambia".270 271Arreglos272~~~~~~~~273Si un cambio corrige un error de KVM/kernel, añada una etiqueta Fixes:274incluso si el cambio no necesita ser retroportado a kernels estables, e275incluso si el cambio corrige un error en una versión anterior.276 277Por el contrario, si es necesario hacer una corrección, etiquete278explícitamente el parche con "Cc: stable@vger.kernel" (aunque no es279necesario que el correo electrónico incluya Cc: stable); KVM x86 opta por280excluirse del backporting Correcciones: por defecto. Algunos parches281seleccionados automáticamente se retroportan, pero requieren la aprobación282explícita de los mantenedores (busque MANUALSEL).283 284Referencias a Funciones285~~~~~~~~~~~~~~~~~~~~~~~286Cuando se mencione una función en un comentario, registro de cambios o287registro abreviado (o en cualquier otro lugar), utilice el formato288``nombre_de_la_función()``. Los paréntesis proporcionan contexto y289desambiguan la referencia.290 291Pruebas292~~~~~~~293Como mínimo, *todos* los parches de una serie deben construirse limpiamente294para KVM_INTEL=m KVM_AMD=m, y KVM_WERROR=y. Construir todas las295combinaciones posibles de Kconfigs no es factible, pero cuantas más mejor.296KVM_SMM, KVM_XEN, PROVE_LOCKING, y X86_64 son particularmente interesantes.297 298También es obligatorio ejecutar las autopruebas y las pruebas unitarias de299KVM (y, como es obvio, las pruebas deben pasar). La única excepción es para300los cambios que tienen una probabilidad insignificante de afectar al301comportamiento en tiempo de ejecución, por ejemplo, parches que sólo302modificar los comentarios. Siempre que sea posible y pertinente, se303recomienda encarecidamente realizar pruebas tanto en Intel como en AMD. Se304recomienda arrancar una máquina virtual real, pero no es obligatorio.305 306Para cambios que afecten al código de paginación en la sombra de KVM, es307obligatorio ejecutar con TDP (EPT/NPT) deshabilitado. Para cambios que308afecten al código MMU común de KVM, se recomienda encarecidamente ejecutar309con TDP deshabilitado. Para todos los demás cambios, si el código que se310está modificando depende de y/o interactúa con un parámetro del módulo, es311obligatorio realizar pruebas con la configuración correspondiente.312 313Tenga en cuenta que las autopruebas de KVM y las pruebas de unidad de KVM314tienen fallos conocidos. Si sospecha que un fallo no se debe a sus cambios,315verifique que el *exactamente el mismo* fallo se produce con y sin sus316cambios.317 318Los cambios que afecten a la documentación de texto reestructurado, es319decir, a los archivos .rst, deben generar htmldocs de forma limpia, es320decir, sin advertencias ni errores.321 322Si no puede probar completamente un cambio, por ejemplo, por falta de323hardware, indique claramente qué nivel de pruebas ha podido realizar, por324ejemplo, en la carta de presentación.325 326Novedades327~~~~~~~~~328Con una excepción, las nuevas características *deben* venir con cobertura329de pruebas. Las pruebas específicas de KVM no son estrictamente necesarias,330por ejemplo, si la cobertura se proporciona mediante la ejecución de una331prueba de VM huésped suficientemente habilitada, o ejecutando una332autoprueba de kernel relacionada en una VM, pero en todos los casos se333prefieren las pruebas KVM dedicadas. Los casos de prueba negativos en334particular son obligatorios para la habilitación de nuevas características335de hardware, ya que los flujos de errores y excepciones rara vez se336ejercitan simplemente ejecutando una VM.337 338La única excepción a esta regla es si KVM está simplemente anunciando339soporte para un a través de KVM_GET_SUPPORTED_CPUID, es decir, para340instrucciones/funciones que KVM no puede impedir que utilice una VM y341para las que no existe una verdadera habilitación.342 343Tenga en cuenta que "nuevas características" no significa sólo "nuevas344características de hardware". Las nuevas funcionalidades que no puedan ser345validadas usando las pruebas existentes de KVM y/o las pruebas unitarias de346KVM deben venir con pruebas.347 348Es más que bienvenido el envío de nuevos desarrollos de características sin349pruebas para obtener un feedback temprano, pero tales envíos deben ser350etiquetados como RFC, y la carta de presentación debe indicar claramente351qué tipo de feedback se solicita/espera. No abuse del proceso de RFC; las352RFC no suelen recibir una revisión en profundidad.353 354Corrección de Errores355~~~~~~~~~~~~~~~~~~~~~356Salvo en el caso de fallos "obvios" detectados por inspección, las357correcciones deben ir acompañadas de un reproductor del fallo corregido. En358muchos casos, el reproductor está implícito, por ejemplo, para errores de359compilación y fallos de prueba, pero debe quedar claro para lectores qué es360lo que no funciona y cómo verificar la solución. Se concede cierto margen a361los errores detectados mediante cargas de trabajo/pruebas no públicas, pero362se recomienda encarecidamente que se faciliten pruebas de regresión para363dichos errores.364 365En general, las pruebas de regresión son preferibles para cualquier fallo366que no sea trivial de encontrar. Por ejemplo, incluso si el error fue367encontrado originalmente por un fuzzer como syzkaller, una prueba de368regresión dirigida puede estar justificada si el error requiere golpear una369condición de carrera de tipo uno en un millón.370 371Recuerde que los fallos de KVM rara vez son urgentes *y* no triviales de372reproducir. Pregúntate si un fallo es realmente el fin del mundo antes de373publicar una corrección sin un reproductor.374 375Publicación376-----------377 378Enlaces379~~~~~~~380No haga referencia explícita a informes de errores, versiones anteriores de381un parche/serie, etc. mediante cabeceras ``In-Reply-To:``. Usar382``In-Reply-To:`` se convierte en un lío para grandes series y/o cuando el383número de versiones es alto, y ``In-Reply-To:`` es inútil para cualquiera384que no tenga el mensaje original, por ejemplo, si alguien no recibió un Cc385en el informe de error o si la lista de destinatarios cambia entre386versiones.387 388Para enlazar con un informe de error, una versión anterior o cualquier cosa389de interés, utiliza enlaces lore. Para hacer referencia a versiones390anteriores, en general no incluya un Enlace: en el registro de cambios, ya391que no hay necesidad de registrar la historia en git, es decir, ponga el392enlace en la carta de presentación o en la sección que git ignora.393Proporcione un Enlace: formal para los informes de errores y/o discusiones394que condujeron al parche. El contexto de por qué se hizo un cambio es muy395valioso para futuros lectores.396 397Basado en Git398~~~~~~~~~~~~~399Si utilizas la versión 2.9.0 o posterior de git (Googlers, ¡os incluimos a400todos!), utilice ``git format-patch`` con el indicador ``--base`` para401incluir automáticamente la información del árbol base en los parches402generados.403 404Tenga en cuenta que ``--base=auto`` funciona como se espera si y sólo si el405upstream de una rama se establece en la rama temática base, por ejemplo,406hará lo incorrecto si su upstream se establece en su repositorio personal407con fines de copia de seguridad. Una solución "automática" alternativa es408derivar los nombres de tus ramas de desarrollo basándose en su KVM x86, e409introdúzcalo en ``--base``. Por ejemplo, ``x86/pmu/mi_nombre_de_rama``, y410luego escribir un pequeño wrapper para extraer ``pmu`` del nombre de la411rama actual para obtener ``--base=x/pmu``, donde ``x`` es el nombre que su412repositorio utiliza para rastrear el remoto KVM x86.413 414Tests de Co-Publicación415~~~~~~~~~~~~~~~~~~~~~~~416Las autopruebas de KVM asociadas a cambios de KVM, por ejemplo, pruebas de417regresión para correcciones de errores, deben publicarse junto con los418cambios de KVM como una única serie. Se aplicarán las reglas estándar del419núcleo para la bisección, es decir, los cambios de KVM que provoquen fallos420en las pruebas se ordenarán después de las actualizaciones de las421autopruebas, y viceversa. Las pruebas que fallan debido a errores de KVM422deben ordenarse después de las correcciones de KVM.423 424KVM-unit-tests debería *siempre* publicarse por separado. Las herramientas,425por ejemplo b4 am, no saben que KVM-unit-tests es un repositorio separado y426se confunden cuando los parches de una serie se aplican en diferentes427árboles. Para vincular los parches de KVM-unit-tests a Parches KVM, primero428publique los cambios KVM y luego proporcione un enlace lore Link: al429parche/serie KVM en el parche(s) KVM-unit-tests.430 431Notificaciones432~~~~~~~~~~~~~~433Cuando se acepte oficialmente un parche/serie, se enviará un correo434electrónico de notificación en respuesta a la publicación original (carta435de presentación para series de varios parches). La notificación incluirá el436árbol y la rama temática, junto con los SHA1 de los commits de los parches437aplicados.438 439Si se aplica un subconjunto de parches, se indicará claramente en la440notificación. A menos que se indique lo contrario, se sobreentiende que441todos los parches del Las series que no han sido aceptadas necesitan más442trabajo y deben presentarse en una nueva versión.443 444Si por alguna razón se retira un parche después de haber sido aceptado445oficialmente, se enviará una respuesta al correo electrónico de446notificación explicando por qué se ha retirado el parche, así como los447pasos siguientes.448 449Estabilidad SHA1450~~~~~~~~~~~~~~~~451Los SHA1 no son 100% estables hasta que llegan al árbol de Linus. Un SHA1452es *normalmente* estable una vez que se ha enviado una notificación, pero453ocurren cosas. En la mayoría de los casos, se proporcionará una454actualización del correo electrónico de notificación si se aplica un SHA1455del parche. Sin embargo, en algunos escenarios, por ejemplo, si todas las456ramas de KVM x86 necesitan ser rebasadas, no se darán notificaciones457individuales.458 459Vulnerabilidades460~~~~~~~~~~~~~~~~461Los fallos que pueden ser explotados por la VM (el "guest") para atacar al462host (kernel o espacio de usuario), o que pueden ser explotados por una VM463anidada a *su* host (L2 atacando a L1), son de particular interés para KVM.464Por favor, siga el protocolo para :ref:`securitybugs` si sospecha que un465fallo puede provocar una filtración de datos, etc.466