From nobody Sun Dec 14 20:28:52 2025 Received: from mail-ot1-f49.google.com (mail-ot1-f49.google.com [209.85.210.49]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 49A4914A4CC; Fri, 29 Nov 2024 15:58:59 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=209.85.210.49 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1732895941; cv=none; b=Lg5A/6EuEEtk65bdERJEDbMkiIF5fMYG27E9SzSUubTa5WpqAtzXFOFIAbBpD7P7IEN88RTlHlkUMYiOXejcpp3IKUXR24XBji+qRMu4bUTY0Cp/efHUQBxZHKyupRM4ffblZcYZQNpRg+UzHzuDICyj52E+L8c6rGmmPFHWfmk= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1732895941; c=relaxed/simple; bh=FN/kgNPUhuXmSgJzmYJC6RBkOk0pUs0foA9dAASqRcg=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=c3YAd6qvYo6VEmmYXrTmIq4vYX/AT8HEvgJ8uMc1ui3uMPvr9bM8IPnhd86IoWeUXvbgmuwBHnE6UzOVKCT1Cl+ngSUXv8U8Ft4oauHhACWhMv4guoViWis1BWR6bPNzEVvHRxyEUqinruxL9Jx3kbOuqx6Z9rcPTl+rlirxNMw= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=gmail.com; spf=pass smtp.mailfrom=gmail.com; dkim=pass (2048-bit key) header.d=gmail.com header.i=@gmail.com header.b=akHnVTSW; arc=none smtp.client-ip=209.85.210.49 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=gmail.com Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=gmail.com Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=gmail.com header.i=@gmail.com header.b="akHnVTSW" Received: by mail-ot1-f49.google.com with SMTP id 46e09a7af769-71d41932d32so778716a34.0; Fri, 29 Nov 2024 07:58:59 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1732895938; x=1733500738; darn=vger.kernel.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:from:to:cc:subject:date :message-id:reply-to; bh=5wJIg/sxtDsSUo2Smlt0dgu9NBkc52JfvgQN+3tMwkU=; b=akHnVTSWljKhXZZdq6lri1lti3F0S85yIbKKIjLna99Wjsevy+QZoFgbWWeme//HYw hdsYeDjPTSvHMqNEcGTogNFgO8wNdfgp1r6w8FhDDYfDwCB81udzVUhOAMX2gjPZrOa3 guG3vCBoCWBq9zdeqSGzmy+aVePDpGejB31a1/Y/paVC3vvKDgIChDI5LskYa1JVa1AM GOeTTQGjnDkVIbkMEdb45V0TE9dnWkVOiucRbAG5pYWBjQ2j1nG/icqBppe6PICnJfP+ hKgI86CebZ5a/hTHfVCWzn0/EpJll8GbSTth3lMWlIffxQ89BldzkbvZ6V5Gf+anWwF+ qbrQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1732895938; x=1733500738; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=5wJIg/sxtDsSUo2Smlt0dgu9NBkc52JfvgQN+3tMwkU=; b=nBDy1pWTS5BhboFJf3a4LmzeRuJbkedjc46FAhWNgkcwiQ8mpZxXKtrZ7gzZL0phV/ zFMj7rvEfw2/f7HK70I89sU+FMkbiWbIO6GRJ8MkAes/ix9HgVmFKDo0EGxThffjy7Bp XM3o0pMXv9qDIEInHz/7NErT18CUlf8mGG0+t5r871YWcgRLM3MGBsbDkyTlmynfsOuP UrBKqoTzP1p4N9NR6WMWQcOwGumHNgbSOLEinsz7C/oA021N+ouwisG7IU8rTxRfvxZt 1t77Ex7OgbXT1XiZHE0VuHik0IyxWpAa1UtNRrhLHhEKIcJ1jbj9jttEiO1DCI4gVMNR ZNpw== X-Forwarded-Encrypted: i=1; AJvYcCUWhiKwyz3nJGKxbvRI3pFXeVcMeYEw9M/8B2C/pVHyHEXmWCn3bJrCi5tpiYypl7TDv6pQ4yqk/cPhfco=@vger.kernel.org X-Gm-Message-State: AOJu0YzGgdgP3DVPTx+uNBA4zvxbaIBFyRXGmBErkSap4vjFFv2I93d/ sp18+4t7hhdDR+Qb1OBCv3oyaNpzcguWuIhgWxhqwPmX1Ot+IPR4 X-Gm-Gg: ASbGncs4XAvAhvkPOI9sDamonp9MS6SDCNxlOvH3NdxyLa2nVG29fUYjncTam9SDFvi pfU+8Wsxdw3sF3NjASQUgaRdclOljw216pCPwDh5n0JY2fiYoFcAUTIopI0BJfh3kZ/hq+2+6me sJYrYnt1ZEZy1dhea80XS7Qczj9GjfBIUTPickEImVB9zH0icdBgQn21ymqWxTnmhR8xaJSOK2j yIwj3tLhlwIp9bIWxu9s288tNj8yDl6IUC2yKaPaK8DeHWE9KN0D8oXdK7oArU9WdRqQ2xFU5Zh X-Google-Smtp-Source: AGHT+IE2VcF/MSwNHS6hN8HzVuhroZFj9OBsXvwDuziygvANH4/lTvjHkaVRJBLDQdldAtq5y9YW8Q== X-Received: by 2002:a05:6830:349a:b0:71d:53b7:6433 with SMTP id 46e09a7af769-71d65a93f2fmr11541443a34.0.1732895937878; Fri, 29 Nov 2024 07:58:57 -0800 (PST) Received: from pipaware.tx.rr.com ([2603:8080:7400:36da:dff5:4180:2562:4c1e]) by smtp.gmail.com with ESMTPSA id 46e09a7af769-71d725f2251sm794385a34.68.2024.11.29.07.58.56 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 29 Nov 2024 07:58:57 -0800 (PST) From: Carlos Bilbao To: corbet@lwn.net, avadhut.naik@amd.com, bilbao@vt.edu Cc: linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org, Carlos Bilbao Subject: [PATCH 2/7] docs/sp_SP: Add translation of process/4.Coding.rst Date: Fri, 29 Nov 2024 09:58:42 -0600 Message-ID: <20241129155851.1023884-3-carlos.bilbao.osdev@gmail.com> X-Mailer: git-send-email 2.43.5 In-Reply-To: <20241129155851.1023884-1-carlos.bilbao.osdev@gmail.com> References: <20241129155851.1023884-1-carlos.bilbao.osdev@gmail.com> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Translate Documentation/process/4.Coding.rst into Spanish. Co-developed-by: Avadhut Naik Signed-off-by: Avadhut Naik Signed-off-by: Carlos Bilbao --- .../translations/sp_SP/process/4.Coding.rst | 463 +++++++++++++++++- .../sp_SP/process/development-process.rst | 1 + 2 files changed, 462 insertions(+), 2 deletions(-) diff --git a/Documentation/translations/sp_SP/process/4.Coding.rst b/Docume= ntation/translations/sp_SP/process/4.Coding.rst index d9436e039b4b..7cc347c34354 100644 --- a/Documentation/translations/sp_SP/process/4.Coding.rst +++ b/Documentation/translations/sp_SP/process/4.Coding.rst @@ -1,11 +1,470 @@ .. include:: ../disclaimer-sp.rst =20 :Original: Documentation/process/4.Coding.rst +:Translator: Carlos Bilbao and Avadhut Nai= k =20 .. _sp_development_coding: =20 Conseguir el c=C3=B3digo correcto =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D =20 -.. warning:: - TODO a=C3=BAn no traducido +Si bien hay mucho que decir a favor de un proceso de dise=C3=B1o s=C3=B3li= do y +orientado a la comunidad, la prueba de cualquier proyecto de desarrollo del +kernel est=C3=A1 en el c=C3=B3digo resultante. Es el c=C3=B3digo lo que se= r=C3=A1 examinado por +otros desarrolladores y lo que ser=C3=A1 incluido (o no) en el =C3=A1rbol = principal. +Por lo tanto, es la calidad de este c=C3=B3digo lo que determinar=C3=A1 el= =C3=A9xito +final del proyecto. + +Esta secci=C3=B3n examinar=C3=A1 el proceso de programaci=C3=B3n. Comenzar= emos observando +algunas de las maneras en que los desarrolladores del kernel pueden cometer +errores. Luego, el enfoque se dirigir=C3=A1 hacia hacer las cosas bien y l= as +herramientas que pueden ayudar en dicha b=C3=BAsqueda. + +Problemas +--------- + +Estilo de programaci=C3=B3n +********************** + +El kernel ha tenido durante mucho tiempo un estilo de programaci=C3=B3n +est=C3=A1ndar, descrito en la documentaci=C3=B3n del kernel en +`Documentation/process/coding-style.rst`. Durante gran parte de ese tiempo, +las pol=C3=ADticas descritas en ese archivo se tomaban como, en el mejor d= e los +casos, orientativas. Como resultado, hay una cantidad considerable de +c=C3=B3digo en el kernel que no cumple con las pautas de estilo de program= aci=C3=B3n. +La presencia de ese c=C3=B3digo lleva a dos peligros independientes para l= os +desarrolladores del kernel. + +El primero de estos es creer que los est=C3=A1ndares de programaci=C3=B3n = del kernel +no importan y no se aplican. La realidad es que agregar nuevo c=C3=B3digo = al +kernel es muy dif=C3=ADcil si ese c=C3=B3digo no est=C3=A1 escrito de acue= rdo con el +est=C3=A1ndar; muchos desarrolladores solicitar=C3=A1n que el c=C3=B3digo = sea reformateado +antes de revisarlo. Una base de c=C3=B3digo tan grande como el kernel requ= iere +cierta uniformidad para que los desarrolladores puedan comprender +r=C3=A1pidamente cualquier parte de =C3=A9l. As=C3=AD que ya no hay lugar = para el c=C3=B3digo +con formato extra=C3=B1o. + +Ocasionalmente, el estilo de programaci=C3=B3n del kernel entrar=C3=A1 en = conflicto +con el estilo obligatorio de un empleador. En tales casos, el estilo del +kernel tendr=C3=A1 que prevalecer antes de que el c=C3=B3digo pueda ser fu= sionado. +Incluir c=C3=B3digo en el kernel significa renunciar a cierto grado de con= trol +de varias maneras, incluida la forma en que se formatea el c=C3=B3digo. + +La otra trampa es asumir que el c=C3=B3digo que ya est=C3=A1 en el kernel = necesita +urgentemente correcciones de estilo de programaci=C3=B3n. Los desarrollado= res +pueden comenzar a generar parches de reformateo como una forma de +familiarizarse con el proceso o como una forma de incluir su nombre en los +registros de cambios del kernel, o ambos. Pero las correcciones puramente +de estilo de programaci=C3=B3n son vistas como ruido por la comunidad de +desarrollo; tienden a recibir una recepci=C3=B3n adversa. Por lo tanto, es= te +tipo de parche es mejor evitarlo. Es natural corregir el estilo de una +parte del c=C3=B3digo mientras se trabaja en =C3=A9l por otras razones, pe= ro los +cambios de estilo de programaci=C3=B3n no deben hacerse por s=C3=AD mismos. + +El documento de estilo de programaci=C3=B3n tampoco debe leerse como una l= ey +absoluta que nunca puede transgredirse. Si hay una buena raz=C3=B3n para i= r en +contra del estilo (una l=C3=ADnea que se vuelve mucho menos legible si se = divide +para ajustarse al l=C3=ADmite de 80 columnas, por ejemplo), perfecto. + +Tenga en cuenta que tambi=C3=A9n puedes usar la herramienta `clang-format`= para +ayudarle con estas reglas, para reformatear r=C3=A1pidamente partes de su = c=C3=B3digo +autom=C3=A1ticamente y para revisar archivos completos a fin de detectar e= rrores +de estilo de programaci=C3=B3n, errores tipogr=C3=A1ficos y posibles mejor= as. Tambi=C3=A9n +es =C3=BAtil para ordenar `#includes`, alinear variables/macros, reformate= ar +texto y otras tareas similares. Consulte el archivo +`Documentation/dev-tools/clang-format.rst` para m=C3=A1s detalles. + +Algunas configuraciones b=C3=A1sicas del editor, como la indentaci=C3=B3n = y los +finales de l=C3=ADnea, se configurar=C3=A1n autom=C3=A1ticamente si utiliz= as un editor +compatible con EditorConfig. Consulte el sitio web oficial de EditorConfig +para obtener m=C3=A1s informaci=C3=B3n: https://editorconfig.org/ + +Capas de abstracci=C3=B3n +******************** + +Los profesores de ciencias de la computaci=C3=B3n ense=C3=B1an a los estud= iantes a +hacer un uso extensivo de capas de abstracci=C3=B3n en nombre de la +flexibilidad y el ocultamiento de la informaci=C3=B3n. Sin duda, el kernel= hace +un uso extensivo de la abstracci=C3=B3n; ning=C3=BAn proyecto que involucr= e varios +millones de l=C3=ADneas de c=C3=B3digo podr=C3=ADa sobrevivir de otra mane= ra. Pero la +experiencia ha demostrado que una abstracci=C3=B3n excesiva o prematura pu= ede +ser tan perjudicial como la optimizaci=C3=B3n prematura. La abstracci=C3= =B3n debe +usarse en la medida necesaria y ya. + +A un nivel simple, considere una funci=C3=B3n que tiene un argumento que s= iempre +se pasa como cero por todos los que la invocan. Uno podr=C3=ADa mantener e= se +argumento por si alguien eventualmente necesita usar la flexibilidad +adicional que proporciona. Sin embargo, para entonces, es probable que el +c=C3=B3digo que implementa este argumento adicional se haya roto de alguna +manera sutil que nunca se not=C3=B3, porque nunca se ha utilizado. O, cuan= do +surge la necesidad de flexibilidad adicional, no lo hace de una manera que +coincida con la expectativa temprana del programador. Los desarrolladores +del kernel rutinariamente enviar=C3=A1n parches para eliminar argumentos no +utilizados; en general, no deber=C3=ADan a=C3=B1adirse en primer lugar. + +Las capas de abstracci=C3=B3n que ocultan el acceso al hardware, a menudo = para +permitir que la mayor parte de un controlador se utilice con varios +sistemas operativos, son especialmente mal vistas. Dichas capas oscurecen +el c=C3=B3digo y pueden imponer una penalizaci=C3=B3n en el rendimiento; no +pertenecen al kernel de Linux. + +Por otro lado, si se encuentra copiando cantidades significativas de c=C3= =B3digo +de otro subsistema del kernel, es hora de preguntar si, de hecho, tendr=C3= =ADa +sentido extraer parte de ese c=C3=B3digo en una biblioteca separada o +implementar esa funcionalidad a un nivel superior. No tiene sentido +replicar el mismo c=C3=B3digo en todo el kernel. + +Uso de #ifdef y del preprocesador en general +******************************************** + +El preprocesador de C tiene una tentaci=C3=B3n poderosa para algunos +programadores de C, quienes lo ven como una forma de programar +eficientemente una gran cantidad de flexibilidad en un archivo fuente. Pero +el preprocesador no es C, y el uso intensivo de =C3=A9l da como resultado = un +c=C3=B3digo mucho m=C3=A1s dif=C3=ADcil de leer para otros y m=C3=A1s dif= =C3=ADcil de verificar por +el compilador para su correcci=C3=B3n. El uso intensivo del preprocesador = es +asi siempre un signo de un c=C3=B3digo que necesita algo de limpieza. + +La compilaci=C3=B3n condicional con `#ifdef` es, de hecho, una caracter=C3= =ADstica +poderosa, y se usa dentro del kernel. Pero hay poco deseo de ver c=C3=B3di= go que +st=C3=A9 salpicado liberalmente con bloques `#ifdef`. Como regla general, = el uso +de `#ifdef` debe limitarse a los archivos de encabezado siempre que sea +posible. El c=C3=B3digo condicionalmente compilado puede confinarse a func= iones +que, si el c=C3=B3digo no va a estar presente, simplemente se convierten en +vac=C3=ADas. El compilador luego optimizar=C3=A1 silenciosamente la llamad= a a la +funci=C3=B3n vac=C3=ADa. El resultado es un c=C3=B3digo mucho m=C3=A1s lim= pio y f=C3=A1cil de +seguir. + +Las macros del preprocesador de C presentan varios peligros, incluida la +posible evaluaci=C3=B3n m=C3=BAltiple de expresiones con efectos secundari= os y la +falta de seguridad de tipos. Si te sientes tentado a definir una macro, +considera crear una funci=C3=B3n en l=C3=ADnea en su lugar. El c=C3=B3digo= resultante ser=C3=A1 +el mismo, pero las funciones en l=C3=ADnea son m=C3=A1s f=C3=A1ciles de le= er, no eval=C3=BAan +sus argumentos varias veces y permiten que el compilador realice +comprobaciones de tipo en los argumentos y el valor de retorno. + +Funciones en l=C3=ADnea +****************** + +Las funciones en l=C3=ADnea presentan su propio peligro, sin embargo. Los +programadores pueden enamorarse de la eficiencia percibida al evitar una +llamada a funci=C3=B3n y llenar un archivo fuente con funciones en l=C3=AD= nea. Esas +funciones, sin embargo, pueden en realidad reducir el rendimiento. Dado que +su c=C3=B3digo se replica en cada sitio de llamada, terminan hinchando el = tama=C3=B1o +del kernel compilado. Eso, a su vez, crea presi=C3=B3n en las cach=C3=A9s = de memoria +del procesador, lo que puede ralentizar la ejecuci=C3=B3n de manera dr=C3= =A1stica +Las funciones en l=C3=ADnea, como regla, deben ser bastante peque=C3=B1as y +relativamente raras. El costo de una llamada a funci=C3=B3n, despu=C3=A9s = de todo, no +es tan alto; la creaci=C3=B3n de un gran n=C3=BAmero de funciones en l=C3= =ADnea es un +ejemplo cl=C3=A1sico de optimizaci=C3=B3n prematura. + +En general, los programadores del kernel ignoran los efectos de cach=C3=A9= bajo +su propio riesgo. El cl=C3=A1sico intercambio de tiempo/espacio que se ens= e=C3=B1a en +las clases de estructuras de datos iniciales a menudo no se aplica al +hardware contempor=C3=A1neo. El espacio *es* tiempo, en el sentido de que = un +programa m=C3=A1s grande se ejecutar=C3=A1 m=C3=A1s lentamente que uno m= =C3=A1s compacto. + +Los compiladores m=C3=A1s recientes toman un papel cada vez m=C3=A1s activ= o al +decidir si una funci=C3=B3n dada debe realmente ser en l=C3=ADnea o no. Po= r lo tanto, +la colocaci=C3=B3n liberal de palabras clave "inline" puede no solo ser +excesiva; tambi=C3=A9n podr=C3=ADa ser irrelevante. + +Bloqueo +******* + +En mayo de 2006, la pila de red "Devicescape" fue, con gran fanfarria, +lanzada bajo la licencia GPL y puesta a disposici=C3=B3n para su inclusi= =C3=B3n en el +kernel principal. Esta donaci=C3=B3n fue una noticia bienvenida; el soport= e para +redes inal=C3=A1mbricas en Linux se consideraba, en el mejor de los casos, +deficiente, y la pila de Devicescape ofrec=C3=ADa la promesa de solucionar= esa +situaci=C3=B3n. Sin embargo, este c=C3=B3digo no fue incluido en el kernel= principal +hasta junio de 2007 (versi=C3=B3n 2.6.22). =C2=BFQu=C3=A9 sucedi=C3=B3? + +Este c=C3=B3digo mostr=C3=B3 varios signos de haber sido desarrollado a pu= ertas +cerradas en una empresa. Pero un problema importante en particular fue que +no estaba dise=C3=B1ado para funcionar en sistemas multiprocesador. Antes = de que +esta pila de red (ahora llamada mac80211) pudiera fusionarse, se tuvo que +implementar un esquema de bloqueo en ella. + +Hubo un tiempo en que se pod=C3=ADa desarrollar c=C3=B3digo para el kernel= de Linux +sin pensar en los problemas de concurrencia que presentan los sistemas +multiprocesador. Ahora, sin embargo, este documento se est=C3=A1 escribien= do en +una computadora port=C3=A1til con dos n=C3=BAcleos. Incluso en sistemas de= un solo +procesador, el trabajo que se est=C3=A1 realizando para mejorar la capacid= ad de +respuesta aumentar=C3=A1 el nivel de concurrencia dentro del kernel. Los d= =C3=ADas en +que se pod=C3=ADa escribir c=C3=B3digo para el kernel sin pensar en el blo= queo han +quedado atr=C3=A1s. + +Cualquier recurso (estructuras de datos, registros de hardware, etc.) que +pueda ser accedido concurrentemente por m=C3=A1s de un hilo debe estar pro= tegido +por un bloqueo. El nuevo c=C3=B3digo debe escribirse teniendo en cuenta es= te +requisito; implementar el bloqueo despu=C3=A9s de que el c=C3=B3digo ya ha= sido +desarrollado es una tarea mucho m=C3=A1s dif=C3=ADcil. Los desarrolladores= del kernel +deben tomarse el tiempo para comprender bien los primitivos de bloqueo +disponibles para elegir la herramienta adecuada para el trabajo. El c=C3= =B3digo +que muestre una falta de atenci=C3=B3n a la concurrencia tendr=C3=A1 un ca= mino +dif=C3=ADcil para ser incluido en el kernel principal. + +Regresiones +*********** + +Un =C3=BAltimo peligro que vale la pena mencionar es el siguiente: puede s= er +tentador realizar un cambio (que puede traer grandes mejoras) que cause un +problema para los usuarios existentes. Este tipo de cambio se llama una +"regresi=C3=B3n", y las regresiones se han vuelto muy mal recibidas en el = kernel +principal. Con pocas excepciones, los cambios que causan regresiones ser= =C3=A1n +revertidos si la regresi=C3=B3n no se puede solucionar de manera oportuna.= Es +mucho mejor evitar la regresi=C3=B3n desde el principio. + +A menudo se argumenta que una regresi=C3=B3n puede justificarse si hace qu= e las +cosas funcionen para m=C3=A1s personas de las que crea problemas. =C2=BFPo= r qu=C3=A9 no +hacer un cambio si trae nueva funcionalidad a diez sistemas por cada uno +que rompe? La mejor respuesta a esta pregunta fue expresada por Linus en +julio de 2007 (traducido): + +:: + + Entonces, no arreglamos errores introduciendo nuevos problemas. Eso + lleva a la locura, y nadie sabe si realmente se avanza. =C2=BFEs dos pasos + adelante, uno atr=C3=A1s, o un paso adelante y dos atr=C3=A1s? + +(https://lwn.net/Articles/243460/). + +Un tipo de regresi=C3=B3n especialmente mal recibido es cualquier tipo de = cambio +en la ABI del espacio de usuario. Una vez que se ha exportado una interfaz +al espacio de usuario, debe ser soportada indefinidamente. Este hecho hace +que la creaci=C3=B3n de interfaces para el espacio de usuario sea +particularmente desafiante: dado que no pueden cambiarse de manera +incompatible, deben hacerse bien desde el principio. Por esta raz=C3=B3n, +siempre se requiere una gran cantidad de reflexi=C3=B3n, documentaci=C3=B3= n clara y +una amplia revisi=C3=B3n para las interfaces del espacio de usuario. + +Herramientas de verificaci=C3=B3n de c=C3=B3digo +************************************** + +Por ahora, al menos, escribir c=C3=B3digo libre de errores sigue siendo un= ideal +que pocos de nosotros podemos alcanzar. Sin embargo, lo que podemos esperar +hacer es detectar y corregir tantos de esos errores como sea posible antes +de que nuestro c=C3=B3digo se integre en el kernel principal. Con ese fin,= los +desarrolladores del kernel han reunido una impresionante variedad de +herramientas que pueden detectar una amplia variedad de problemas oscuros +de manera automatizada. Cualquier problema detectado por el ordenador es +un problema que no afectar=C3=A1 a un usuario m=C3=A1s adelante, por lo qu= e es l=C3=B3gico +que las herramientas automatizadas se utilicen siempre que sea posible. + +El primer paso es simplemente prestar atenci=C3=B3n a las advertencias +producidas por el compilador. Las versiones contempor=C3=A1neas de gcc pue= den +detectar (y advertir sobre) una gran cantidad de errores potenciales. Con +bastante frecuencia, estas advertencias apuntan a problemas reales. El +c=C3=B3digo enviado para revisi=C3=B3n no deber=C3=ADa, por regla general,= producir +ninguna advertencia del compilador. Al silenciar las advertencias, tenga +cuidado de comprender la causa real e intente evitar "correcciones" que +hagan desaparecer la advertencia sin abordar su causa. + +Tenga en cuenta que no todas las advertencias del compilador est=C3=A1n +habilitadas de forma predeterminada. Compile el kernel con +"make KCFLAGS=3D-W" para obtener el conjunto completo. + +El kernel proporciona varias opciones de configuraci=C3=B3n que activan +funciones de depuraci=C3=B3n; la mayor=C3=ADa de estas se encuentran en el= submen=C3=BA +"kernel hacking". Varias de estas opciones deben estar activadas para +cualquier kernel utilizado para desarrollo o pruebas. En particular, +deber=C3=ADa activar: + + - FRAME_WARN para obtener advertencias sobre marcos de pila m=C3=A1s gran= des + que una cantidad determinada. La salida generada puede ser extensa, pero + no es necesario preocuparse por las advertencias de otras partes del + kernel. + + - DEBUG_OBJECTS agregar=C3=A1 c=C3=B3digo para rastrear la vida =C3=BAtil= de varios + objetos creados por el kernel y advertir cuando se realicen cosas fuera + de orden. Si est=C3=A1 agregando un subsistema que crea (y exporta) obj= etos + complejos propios, considere agregar soporte para la infraestructura de + depuraci=C3=B3n de objetos. + + - DEBUG_SLAB puede encontrar una variedad de errores en la asignaci=C3=B3= n y + uso de memoria; debe usarse en la mayor=C3=ADa de los kernels de desarr= ollo. + + - DEBUG_SPINLOCK, DEBUG_ATOMIC_SLEEP y DEBUG_MUTEXES encontrar=C3=A1n una= serie + de errores comunes de bloqueo. + +Hay bastantes otras opciones de depuraci=C3=B3n, algunas de las cuales se +discutir=C3=A1n m=C3=A1s adelante. Algunas de ellas tienen un impacto sign= ificativo +en el rendimiento y no deben usarse todo el tiempo. Pero dedicar tiempo a +aprender las opciones disponibles probablemente ser=C3=A1 recompensado muc= has +veces en poco tiempo. + +Una de las herramientas de depuraci=C3=B3n m=C3=A1s pesadas es el verifica= dor de +bloqueos, o "lockdep". Esta herramienta rastrear=C3=A1 la adquisici=C3=B3n= y +liberaci=C3=B3n de cada bloqueo (spinlock o mutex) en el sistema, el orden= en +que se adquieren los bloqueos en relaci=C3=B3n entre s=C3=AD, el entorno a= ctual de +interrupci=C3=B3n, y m=C3=A1s. Luego, puede asegurarse de que los bloqueos= siempre se +adquieran en el mismo orden, que las mismas suposiciones de interrupci=C3= =B3n se +apliquen en todas las situaciones, y as=C3=AD sucesivamente. En otras pala= bras, +lockdep puede encontrar varios escenarios en los que el sistema podr=C3=AD= a, en +raras ocasiones, bloquearse. Este tipo de problema puede ser doloroso +(tanto para desarrolladores como para usuarios) en un sistema desplegado; +lockdep permite encontrarlos de manera automatizada con anticipaci=C3=B3n.= El +c=C3=B3digo con cualquier tipo de bloqueo no trivial debe ejecutarse con l= ockdep +habilitado antes de ser enviado para su inclusi=C3=B3n. + +Como programador diligente del kernel, sin duda alguna, verificar=C3=A1 el +estado de retorno de cualquier operaci=C3=B3n (como una asignaci=C3=B3n de= memoria) +que pueda fallar. Sin embargo, el hecho es que las rutas de recuperaci=C3= =B3n de +fallos resultantes probablemente no hayan sido probadas en absoluto. El +c=C3=B3digo no probado tiende a ser c=C3=B3digo roto; podr=C3=ADa tener mu= cha m=C3=A1s +confianza en su c=C3=B3digo si todas esas rutas de manejo de errores se hu= bieran +ejercitado algunas veces. + +El kernel proporciona un marco de inyecci=C3=B3n de fallos que puede hacer +precisamente eso, especialmente donde est=C3=A1n involucradas las asignaci= ones +de memoria. Con la inyecci=C3=B3n de fallos habilitada, un porcentaje +configurable de las asignaciones de memoria fallar=C3=A1n; estas fallas pu= eden +restringirse a un rango espec=C3=ADfico de c=C3=B3digo. Ejecutar con la in= yecci=C3=B3n de +fallos habilitada permite al programador ver c=C3=B3mo responde el c=C3=B3= digo cuando +las cosas van mal. Consulte +Documentation/fault-injection/fault-injection.rst para obtener m=C3=A1s +informaci=C3=B3n sobre c=C3=B3mo utilizar esta funcionalidad. + +Otros tipos de errores se pueden encontrar con la herramienta de an=C3=A1l= isis +est=C3=A1tico "sparse". Con sparse, el programador puede recibir advertenc= ias +sobre confusiones entre direcciones del espacio de usuario y del kernel, +mezcla de cantidades big-endian y little-endian, el paso de valores enteros +donde se espera un conjunto de banderas de bits, y as=C3=AD sucesivamente. +Sparse debe instalarse por separado (puede encontrarse en +https://sparse.wiki.kernel.org/index.php/Main_Page si su distribuci=C3=B3n= no lo +empaqueta); luego, puede ejecutarse en el c=C3=B3digo agregando "C=3D1" a = su +comando make. + +La herramienta "Coccinelle" (http://coccinelle.lip6.fr/) puede encontrar +una amplia variedad de posibles problemas de codificaci=C3=B3n; tambi=C3= =A9n puede +proponer correcciones para esos problemas. Bastantes "parches sem=C3=A1nti= cos" +para el kernel se han empaquetado en el directorio scripts/coccinelle; +ejecutar "make coccicheck" ejecutar=C3=A1 esos parches sem=C3=A1nticos e i= nformar=C3=A1 +sobre cualquier problema encontrado. Consulte: +ref:`Documentation/dev-tools/coccinelle.rst ` para +obtener m=C3=A1s informaci=C3=B3n. + +Otros tipos de errores de portabilidad se encuentran mejor compilando su +c=C3=B3digo para otras arquitecturas. Si no tiene un sistema S/390 o una p= laca +de desarrollo Blackfin a mano, a=C3=BAn puede realizar el paso de compilac= i=C3=B3n. +Un gran conjunto de compiladores cruzados para sistemas x86 se puede +encontrar en + + https://www.kernel.org/pub/tools/crosstool/ + +Muchos sistemas de compilaci=C3=B3n disponibles comercialmente tambi=C3=A9= n se pueden +utilizar para compilar c=C3=B3digo de kernel para una amplia gama de +arquitecturas. + +Los desarrolladores del kernel son afortunados: tienen acceso a una +variedad de herramientas de verificaci=C3=B3n de c=C3=B3digo de la que los +desarrolladores de la mayor=C3=ADa de los otros sistemas pueden estar celo= sos. +Pero todas esas herramientas no servir=C3=A1n de nada si no las usa. El +resultado final de ignorar estas herramientas es simple: alguien m=C3=A1s = puede +notificarle de un problema en su c=C3=B3digo a trav=C3=A9s de un "oportuno" +comentario en la lista de correo o, peor a=C3=BAn, el c=C3=B3digo problem= =C3=A1tico podr=C3=ADa +ser eliminado. Es mucho m=C3=A1s f=C3=A1cil usar estas herramientas en pri= mer lugar. + +Documentaci=C3=B3n +************* + +La documentaci=C3=B3n a menudo ha sido m=C3=A1s la excepci=C3=B3n que la r= egla en el +desarrollo del kernel. Aun as=C3=AD, una documentaci=C3=B3n adecuada ayuda= r=C3=A1 a +facilitar la integraci=C3=B3n de nuevo c=C3=B3digo en el kernel, har=C3=A1= la vida m=C3=A1s +f=C3=A1cil a otros desarrolladores, y ser=C3=A1 =C3=BAtil para sus usuario= s. En muchos +casos, la inclusi=C3=B3n de documentaci=C3=B3n se ha vuelto esencialmente +obligatoria. + +La primera pieza de documentaci=C3=B3n para cualquier parche es su changel= og +asociado. Las entradas de registro deben describir el problema que se est= =C3=A1 +esolviendo, la forma de la soluci=C3=B3n, las personas que trabajaron en el +parche, cualquier efecto relevante en el rendimiento, y cualquier otra cosa +que pueda ser necesaria para entender el parche. Aseg=C3=BArese de que el +changelog diga *por qu=C3=A9* el parche vale la pena ser aplicado; un +sorprendente n=C3=BAmero de desarrolladores no proporciona esa informaci= =C3=B3n. + +Cualquier c=C3=B3digo que agregue una nueva interfaz para el espacio de us= uario, +incluidos los nuevos archivos de sysfs o /proc, debe incluir documentaci= =C3=B3n +de esa interfaz que permita a los desarrolladores del espacio de usuario +saber con qu=C3=A9 est=C3=A1n trabajando. Consulte `Documentation/ABI/READ= ME` para +una descripci=C3=B3n de c=C3=B3mo debe formatearse esta documentaci=C3=B3n= y qu=C3=A9 +informaci=C3=B3n debe proporcionarse. + +El archivo +:ref:`Documentation/admin-guide/kernel-parameters.rst ` +describe todos los par=C3=A1metros de arranque del kernel. Cualquier parch= e que +agregue nuevos par=C3=A1metros debe agregar las entradas correspondientes = a este +archivo. + +Cualquier nueva opci=C3=B3n de configuraci=C3=B3n debe ir acompa=C3=B1ada = de un texto de +ayuda que explique claramente las opciones y cu=C3=A1ndo el usuario podr= =C3=ADa +querer seleccionarlas. + +La informaci=C3=B3n de la API interna para muchos subsistemas est=C3=A1 do= cumentada +mediante comentarios especialmente formateados; estos comentarios pueden +extraerse y formatearse de diversas maneras mediante el script +"kernel-doc". Si est=C3=A1 trabajando dentro de un subsistema que tiene +comentarios de kerneldoc, debe mantenerlos y agregarlos seg=C3=BAn corresp= onda +para las funciones disponibles externamente. Incluso en =C3=A1reas que no = han +sido tan documentadas, no hay ning=C3=BAn inconveniente en agregar comenta= rios +de kerneldoc para el futuro; de hecho, esta puede ser una actividad =C3=BA= til +para desarrolladores de kernel principiantes. El formato de estos +comentarios, junto con alguna informaci=C3=B3n sobre c=C3=B3mo crear plant= illas de +kerneldoc, se puede encontrar en +:ref:`Documentation/doc-guide/ `. + +Cualquiera que lea una cantidad significativa de c=C3=B3digo existente del +kernel notar=C3=A1 que, a menudo, los comentarios son notables por su ause= ncia. +Una vez m=C3=A1s, las expectativas para el nuevo c=C3=B3digo son m=C3=A1s = altas que en el +pasado; integrar c=C3=B3digo sin comentarios ser=C3=A1 m=C3=A1s dif=C3=ADc= il. Dicho esto, hay +poco deseo de tener c=C3=B3digo excesivamente comentado. El c=C3=B3digo en= s=C3=AD debe +ser legible, con comentarios que expliquen los aspectos m=C3=A1s sutiles. + +Ciertas cosas siempre deben comentarse. El uso de barreras de memoria debe +ir acompa=C3=B1ado de una l=C3=ADnea que explique por qu=C3=A9 la barrera = es necesaria. +Las reglas de bloqueo para las estructuras de datos generalmente necesitan +explicarse en alg=C3=BAn lugar. Las estructuras de datos importantes en ge= neral +necesitan documentaci=C3=B3n completa. Las dependencias no obvias entre +fragmentos de c=C3=B3digo separados deben se=C3=B1alarse. Cualquier cosa q= ue pueda +tentar a un maintainer de c=C3=B3digo a hacer una "limpieza" incorrecta ne= cesita +un comentario que explique por qu=C3=A9 se hace de esa manera. Y as=C3=AD +sucesivamente. + +Cambios en la API interna +************************* + +La interfaz binaria proporcionada por el kernel al espacio de usuario no se +puede romper, excepto en las circunstancias m=C3=A1s graves. Las interface= s de +programaci=C3=B3n internas del kernel, en cambio, son altamente fluidas y = pueden +cambiarse cuando surge la necesidad. Si usted se encuentra teniendo que +hacer un rodeo alrededor de una API del kernel, o simplemente no utilizando +una funcionalidad espec=C3=ADfica porque no cumple con sus necesidades, eso +puede ser una se=C3=B1al de que la API necesita cambiar. Como desarrollado= r del +kernel, usted est=C3=A1 autorizado a hacer esos cambios. + +Hay, por supuesto, algunas condiciones. Los cambios en la API se pueden +hacer, pero necesitan estar bien justificados. Entonces, cualquier parche +que realice un cambio en la API interna debe ir acompa=C3=B1ado de una +descripci=C3=B3n de cu=C3=A1l es el cambio y por qu=C3=A9 es necesario. Es= te tipo de +cambio tambi=C3=A9n debe desglosarse en un parche separado, en lugar de es= tar +enterrado dentro de un parche m=C3=A1s grande. + +La otra condici=C3=B3n es que un desarrollador que cambia una API interna +generalmente est=C3=A1 encargado de la tarea de corregir cualquier c=C3=B3= digo dentro +del =C3=A1rbol del kernel que se vea afectado por el cambio. Para una func= i=C3=B3n +ampliamente utilizada, este deber puede llevar a literalmente cientos o +miles de cambios, muchos de los cuales probablemente entren en conflicto +con el trabajo que otros desarrolladores est=C3=A1n realizando. No hace fa= lta +decir que esto puede ser un trabajo grande, por lo que es mejor asegurarse +de que la justificaci=C3=B3n sea s=C3=B3lida. Tenga en cuenta que la herra= mienta +Coccinelle puede ayudar con los cambios de API a gran escala. + +Cuando se realice un cambio incompatible en la API, siempre que sea +posible, se debe asegurar que el c=C3=B3digo que no ha sido actualizado sea +detectado por el compilador. Esto le ayudar=C3=A1 a estar seguro de que ha +encontrado todos los usos en el =C3=A1rbol de esa interfaz. Tambi=C3=A9n a= lertar=C3=A1 a +los desarrolladores de c=C3=B3digo fuera del =C3=A1rbol de que hay un camb= io al que +necesitan responder. Apoyar el c=C3=B3digo fuera del =C3=A1rbol no es algo= de lo que +los desarrolladores del kernel deban preocuparse, pero tampoco tenemos que +dificultarles la vida m=C3=A1s de lo necesario. diff --git a/Documentation/translations/sp_SP/process/development-process.r= st b/Documentation/translations/sp_SP/process/development-process.rst index 8a967e569772..62ee4b2e109e 100644 --- a/Documentation/translations/sp_SP/process/development-process.rst +++ b/Documentation/translations/sp_SP/process/development-process.rst @@ -26,3 +26,4 @@ para entenderla. 1.Intro 2.Process 3.Early-stage + 4.Coding --=20 2.43.0