From patchwork Thu Nov 24 17:02:37 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Carlos Bilbao X-Patchwork-Id: 25637 Return-Path: Delivered-To: ouuuleilei@gmail.com Received: by 2002:adf:f944:0:0:0:0:0 with SMTP id q4csp3511458wrr; Thu, 24 Nov 2022 09:05:16 -0800 (PST) X-Google-Smtp-Source: AA0mqf4niFCGZrn44qTyIUEw1RK2ei205U6C8U8zOQbH0iiw5fIgls2oUDHc5ps3TvIHCVXWEIM8 X-Received: by 2002:a05:6402:4498:b0:458:8e63:d667 with SMTP id er24-20020a056402449800b004588e63d667mr29002799edb.354.1669309515844; Thu, 24 Nov 2022 09:05:15 -0800 (PST) ARC-Seal: i=2; a=rsa-sha256; t=1669309515; cv=pass; d=google.com; s=arc-20160816; b=lxbeNOI122gormBpidCGg8yIUKPudsxV3uG6ljrWOx7FMSQbX5tAizI226B/kaMlLz rTRqyBU2UDWzMNeqQgNO+CxfpNIPnc4dFSvFynBSD4vMgDdZMDGHO1vSRJpkSwG5PxIQ /vAattEIIVvaCxvKr7gL4AWHOllvnRlNYsj4oOutmquzKkWSN/L2PsDU8Ie5CuK6Nycd EKTyUeiuC34jqBeG0dxDx5CYZHbPJpeMIOMNiWSsFSwG7PYQmgHz7KRn6VrexH0hCw7/ P+WcStFgXcFOSOCivA33lNLCX7zlqAZwIc+5+ePKTRq6vWpk4Ed54/EDNXG+vDq6ZYQ/ fNKg== ARC-Message-Signature: i=2; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=list-id:precedence:content-transfer-encoding:mime-version :references:in-reply-to:message-id:date:subject:cc:to:from :dkim-signature; bh=rCxUi6Ej7HAvB3psTTvfKgksiyqOsMWJpEj0jytfAls=; b=zmzxfWwGxzyifl37JCcmlQWZAnrZrW1LJf9ZhXZJWiC8pLIUQZ4WMl/JNIlVsOsaR8 SxoH91gTAvkpgzDmLRcTl5M6JDVG4lohnn+TrTeB1mRUyPQy1oNbcd7jYAwcAiBWTitr 4H/aj4E2SJHGzvVCn8TBAy4nqT92EmJowmGSu64ARMG5bo68i142RwZAk9pATAS6fwTa WmFmlvChDjuj6wE+g+1NbCKAZfUO+YH+IM155vJ3HIhY9dq8KC85Wjx1VrQOlQkZQ7o/ I1Yu5b7lZljZN/va9zZKo7pQauu8HRipwLYxPfydRvO991a4IMSK4c4H/Qw530skBQvF 231A== ARC-Authentication-Results: i=2; mx.google.com; dkim=pass header.i=@amd.com header.s=selector1 header.b=OzRkX2Qb; arc=pass (i=1 spf=pass spfdomain=amd.com dmarc=pass fromdomain=amd.com); spf=pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org; dmarc=pass (p=QUARANTINE sp=QUARANTINE dis=NONE) header.from=amd.com Received: from out1.vger.email (out1.vger.email. [2620:137:e000::1:20]) by mx.google.com with ESMTP id z24-20020a170906075800b007ae61d89b28si1153598ejb.977.2022.11.24.09.04.41; Thu, 24 Nov 2022 09:05:15 -0800 (PST) Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) client-ip=2620:137:e000::1:20; Authentication-Results: mx.google.com; dkim=pass header.i=@amd.com header.s=selector1 header.b=OzRkX2Qb; arc=pass (i=1 spf=pass spfdomain=amd.com dmarc=pass fromdomain=amd.com); spf=pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org; dmarc=pass (p=QUARANTINE sp=QUARANTINE dis=NONE) header.from=amd.com Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S229670AbiKXRCu (ORCPT + 99 others); Thu, 24 Nov 2022 12:02:50 -0500 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:58986 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S229615AbiKXRCt (ORCPT ); Thu, 24 Nov 2022 12:02:49 -0500 Received: from NAM10-MW2-obe.outbound.protection.outlook.com (mail-mw2nam10on2052.outbound.protection.outlook.com [40.107.94.52]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 269CA28E17; Thu, 24 Nov 2022 09:02:48 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; s=arcselector9901; d=microsoft.com; cv=none; b=T5Ttxe5rm9O9zhrB/SM0kgOCFQWBioV2UJvF3N/ciOupKRywOyXzBfLLG1LFbhFtTvWGCQEDesPdDbxJS68DX9FzPMf47I+RFNEYqhKLwR+T5+s6mxC5v3A+6z2A7TZkWmWhgQ6vP3Uuvip4N7ZQRNOKcK6ir/LgaLIKqXvmXoflnKVt77HVz+gjG7/bsJTstdW7YogJ2jYV0SUOEtIQzjfxFr/KJCqn0kKwmtTzU97gA6/+pdZs69gOKikJfjXB3f2zaLlzXXeouKs/PQUnKsUFi7Ei2dJGNHbfagUMzfgKsHeDf9+ZFEE5CLH8s0IyVuOjqkeGSmwYJSl07S/sPg== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=microsoft.com; s=arcselector9901; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-AntiSpam-MessageData-ChunkCount:X-MS-Exchange-AntiSpam-MessageData-0:X-MS-Exchange-AntiSpam-MessageData-1; bh=rCxUi6Ej7HAvB3psTTvfKgksiyqOsMWJpEj0jytfAls=; b=hoIFUrTaMurZS0jLUR2JB1Ezs510lYxC5YpyfEyAIU4a/Cnefe4ySN44wtQroLeIV5GtdCO2LPIRglBn8Y8A4zx6yLF8QZYZ0XPTkUmkIA/G/s9vFkATf2TxaJARb3dcZGg8dEFk557clr0hCI6ducC8b20cY8cCKa4c2lN8iqo3N6WD0MQpUZwBpBQjovB3HTue2rQxvfSVKBhov4+RmAdTGWLH9jrVOea3u97e876/Gpa300FzgnDTdylnMKfweZDTg0gWqEXlX2o3OPX88KBDsiKX78m3nXUd8lRYDj8PHwJDBgpthtgPcatYatcmHiET9l+Vm4lcy/RzwY3YrQ== ARC-Authentication-Results: i=1; mx.microsoft.com 1; spf=pass (sender ip is 165.204.84.17) smtp.rcpttodomain=lwn.net smtp.mailfrom=amd.com; dmarc=pass (p=quarantine sp=quarantine pct=100) action=none header.from=amd.com; dkim=none (message not signed); arc=none DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=amd.com; s=selector1; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-SenderADCheck; bh=rCxUi6Ej7HAvB3psTTvfKgksiyqOsMWJpEj0jytfAls=; b=OzRkX2QbFUxDtBgn5ujugXrVz8s/IF+NpSbwWxDqXzCbG22GUC7hRLKLc6Y2RcwTE4yE6SM0Im9UMwSLAfirjb1dqU28TPnH/LH35mVVq2TWjqotdU+BpHkwtf3pH2cbD6d7gNbxs2jP+vi/XP6MPo5OCew+SIzxRo/5b+Rixys= Received: from MW4PR03CA0193.namprd03.prod.outlook.com (2603:10b6:303:b8::18) by DS0PR12MB7946.namprd12.prod.outlook.com (2603:10b6:8:151::13) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.5857.17; Thu, 24 Nov 2022 17:02:46 +0000 Received: from CO1NAM11FT059.eop-nam11.prod.protection.outlook.com (2603:10b6:303:b8:cafe::7d) by MW4PR03CA0193.outlook.office365.com (2603:10b6:303:b8::18) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.5857.19 via Frontend Transport; Thu, 24 Nov 2022 17:02:46 +0000 X-MS-Exchange-Authentication-Results: spf=pass (sender IP is 165.204.84.17) smtp.mailfrom=amd.com; dkim=none (message not signed) header.d=none;dmarc=pass action=none header.from=amd.com; Received-SPF: Pass (protection.outlook.com: domain of amd.com designates 165.204.84.17 as permitted sender) receiver=protection.outlook.com; client-ip=165.204.84.17; helo=SATLEXMB04.amd.com; pr=C Received: from SATLEXMB04.amd.com (165.204.84.17) by CO1NAM11FT059.mail.protection.outlook.com (10.13.174.160) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256) id 15.20.5857.18 via Frontend Transport; Thu, 24 Nov 2022 17:02:45 +0000 Received: from SATLEXMB05.amd.com (10.181.40.146) by SATLEXMB04.amd.com (10.181.40.145) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256) id 15.1.2375.34; Thu, 24 Nov 2022 11:02:44 -0600 Received: from SATLEXMB04.amd.com (10.181.40.145) by SATLEXMB05.amd.com (10.181.40.146) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256) id 15.1.2375.34; Thu, 24 Nov 2022 11:02:44 -0600 Received: from iron-maiden.amd.com (10.180.168.240) by SATLEXMB04.amd.com (10.181.40.145) with Microsoft SMTP Server id 15.1.2375.34 via Frontend Transport; Thu, 24 Nov 2022 11:02:43 -0600 From: Carlos Bilbao To: , , CC: , , , Carlos Bilbao Subject: [PATCH 1/6] docs: Update maintainer of kernel-docs.rst Date: Thu, 24 Nov 2022 11:02:37 -0600 Message-ID: <20221124170242.1892751-2-carlos.bilbao@amd.com> X-Mailer: git-send-email 2.34.1 In-Reply-To: <20221124170242.1892751-1-carlos.bilbao@amd.com> References: <20221124170242.1892751-1-carlos.bilbao@amd.com> MIME-Version: 1.0 X-EOPAttributedMessage: 0 X-MS-PublicTrafficType: Email X-MS-TrafficTypeDiagnostic: CO1NAM11FT059:EE_|DS0PR12MB7946:EE_ X-MS-Office365-Filtering-Correlation-Id: eff32887-6a65-4e0b-a337-08dace3db552 X-MS-Exchange-SenderADCheck: 1 X-MS-Exchange-AntiSpam-Relay: 0 X-Microsoft-Antispam: BCL:0; X-Microsoft-Antispam-Message-Info: Q9TvzAEsBcXVcjrzTApq93Ze5U9DgfdywWnhVLmNjzLJI75R5C4UjRLWQHxdv3uMawmGrPl2T5Bn6fISFjuLVZ1+J/FmOWzQUbw9nw67CD5skP+T/KDZ8Ihn06SBHcqDHq1tLps+H1oW268GhXcJB9K6rwmcN0cgpvL6fuzZoB+DF39UOT1eBHYviMQVY8ChfBAjdbQ/NZRvDzOFza0+bStTaIb53qDEurD1oXqanlqhyoM49D5bAKVscLyjSuW987OMgkxVzjYVBZiFtuE1ANZWMXI9IdmdrVbnGkcYqEym3tVxpusAC6IjmvXXAnE7DIamzkcmDALgJJ39J843JBAVkn8NgfSson0NiOPx0UIfeAAV0X/iEuK3CFe+Janeu10eowZAe0X/A+Fa+cX52QQqmEHosalVDmpQnzwo76sfSAQZ1Gb5O92lz8fI1uBobNdWA3JX+YQh0wTS11DmBdn1IiPH6MwzWM3ih7/t6FQzi/HRatSQJm5Xgfvcj4v9K4oTe+rgzAEjiE8j9VUsuF8gIvdB6u33XpSWwXIL1GtjAFY/h/Ke2JmKk/Qa++Ay1Lu8d76EUd1ez+URPxEA4RcAXTGoa8MyUfiy98Tl7XOM2Z/Nj2Uwt1AfWnBA6B3LKdyWcIwosF2dAvLPDyP3DS20tC5SeFIJcbM66AaghVj8R49Bh7MRyNgf6Wt+ttp/rftrNc14xmk2udml/SRfgmvZWmJXXuD/e3AXryfMDitLJpRCz3gAS7gTCm7F8g2BdOvVy6clm9kqezJN7WfOI2LTgJ4enKd0frBx/383ik11nUENzazKs3HT58ak9sAw X-Forefront-Antispam-Report: CIP:165.204.84.17;CTRY:US;LANG:en;SCL:1;SRV:;IPV:CAL;SFV:NSPM;H:SATLEXMB04.amd.com;PTR:InfoDomainNonexistent;CAT:NONE;SFS:(13230022)(4636009)(39860400002)(136003)(396003)(346002)(376002)(451199015)(40470700004)(36840700001)(46966006)(15650500001)(44832011)(36756003)(2906002)(40460700003)(186003)(316002)(82310400005)(426003)(86362001)(2616005)(70586007)(70206006)(8936002)(110136005)(47076005)(81166007)(54906003)(356005)(40480700001)(83380400001)(5660300002)(4326008)(6666004)(8676002)(1076003)(26005)(966005)(336012)(478600001)(82740400003)(7696005)(41300700001)(36860700001)(36900700001);DIR:OUT;SFP:1101; X-OriginatorOrg: amd.com X-MS-Exchange-CrossTenant-OriginalArrivalTime: 24 Nov 2022 17:02:45.5359 (UTC) X-MS-Exchange-CrossTenant-Network-Message-Id: eff32887-6a65-4e0b-a337-08dace3db552 X-MS-Exchange-CrossTenant-Id: 3dd8961f-e488-4e60-8e11-a82d994e183d X-MS-Exchange-CrossTenant-OriginalAttributedTenantConnectingIp: TenantId=3dd8961f-e488-4e60-8e11-a82d994e183d;Ip=[165.204.84.17];Helo=[SATLEXMB04.amd.com] X-MS-Exchange-CrossTenant-AuthSource: CO1NAM11FT059.eop-nam11.prod.protection.outlook.com X-MS-Exchange-CrossTenant-AuthAs: Anonymous X-MS-Exchange-CrossTenant-FromEntityHeader: HybridOnPrem X-MS-Exchange-Transport-CrossTenantHeadersStamped: DS0PR12MB7946 X-Spam-Status: No, score=-2.1 required=5.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID,DKIM_VALID_AU,DKIM_VALID_EF,RCVD_IN_DNSWL_NONE, RCVD_IN_MSPIKE_H2,SPF_HELO_PASS,SPF_PASS autolearn=ham autolearn_force=no version=3.4.6 X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on lindbergh.monkeyblade.net Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org X-getmail-retrieved-from-mailbox: =?utf-8?q?INBOX?= X-GMAIL-THRID: =?utf-8?q?1750397895009299509?= X-GMAIL-MSGID: =?utf-8?q?1750397895009299509?= Set new maintainer of the Index of Further Kernel Documentation (document process/kernel_docs.rst). See Link for further context. Also remove line that keeps record of last update of the text -this information is already available elsewhere. Link: https://lore.kernel.org/lkml/20221118170942.2588412-1-carlos.bilbao@amd.com/ Reviewed-by: Miguel Ojeda Signed-off-by: Carlos Bilbao --- Documentation/process/kernel-docs.rst | 8 +++----- MAINTAINERS | 5 +++++ 2 files changed, 8 insertions(+), 5 deletions(-) diff --git a/Documentation/process/kernel-docs.rst b/Documentation/process/kernel-docs.rst index 306ad373a002..5e533c827cef 100644 --- a/Documentation/process/kernel-docs.rst +++ b/Documentation/process/kernel-docs.rst @@ -3,9 +3,6 @@ Index of Further Kernel Documentation ===================================== -Initial Author: Juan-Mariano de Goyeneche (; -email address is defunct now.) - The need for a document like this one became apparent in the linux-kernel mailing list as the same questions, asking for pointers to information, appeared again and again. @@ -614,7 +611,8 @@ Miscellaneous ------- -Document last updated on Tue 2016-Sep-20 +This document was originally based on: -This document is based on: https://www.dit.upm.es/~jmseyas/linux/kernel/hackers-docs.html + +and written by Juan-Mariano de Goyeneche diff --git a/MAINTAINERS b/MAINTAINERS index 6f2ec7c71a4c..05a76d045df8 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -10017,6 +10017,11 @@ F: Documentation/hwmon/ina2xx.rst F: drivers/hwmon/ina2xx.c F: include/linux/platform_data/ina2xx.h +INDEX OF FURTHER KERNEL DOCUMENTATION +M: Carlos Bilbao +S: Maintained +F: Documentation/process/kernel-docs.rst + INDUSTRY PACK SUBSYSTEM (IPACK) M: Samuel Iglesias Gonsalvez M: Jens Taprogge From patchwork Thu Nov 24 17:02:38 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Carlos Bilbao X-Patchwork-Id: 25636 Return-Path: Delivered-To: ouuuleilei@gmail.com Received: by 2002:adf:f944:0:0:0:0:0 with SMTP id q4csp3511439wrr; Thu, 24 Nov 2022 09:05:14 -0800 (PST) X-Google-Smtp-Source: AA0mqf404ZRUTm9iLeokuVV4FGk+stUD8t5hUSQh4T2pW4XBa/CshSKhy/CJ7HbuEhpnPS46qgVr X-Received: by 2002:a17:906:448d:b0:7ae:37aa:6bf with SMTP id y13-20020a170906448d00b007ae37aa06bfmr28366774ejo.481.1669309513694; Thu, 24 Nov 2022 09:05:13 -0800 (PST) ARC-Seal: i=2; a=rsa-sha256; t=1669309513; cv=pass; d=google.com; s=arc-20160816; b=ibTNNXlMfOFHI7BOxbHr3izPOLDsEapHtrzhT8AlxG4J6Y3B7TJChmj36wc5UTgkg+ nQoFRzu5FyvjsKUrjRS+I+tKq3DcZxAGveWKz5TfsFBFcrSEGW2XSF+5yIc3DTOReyuY pn5//9DG25lDnKYE7hJRkgom9YR67rPDtZTWnHgH9KZq2yxS/Nzmtge5IzKoaCssqGJI 0STNkG2MKhCtKu1iiM/lq85aDuTSqeqAfHJdI2e0PyGB4s4exjqaioxANQBWy6yWKHPK MEHv+NEV4wF9ISM2tvcz1aQReNEc9++D4xDHAYVJjR7f0Pxepzaun8xoARglZxVY7UKK QaRQ== ARC-Message-Signature: i=2; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=list-id:precedence:content-transfer-encoding:mime-version :references:in-reply-to:message-id:date:subject:cc:to:from :dkim-signature; bh=a9E5jl5WbHOb0/upQL3rnlHQsW50EnCihMxYedW5nKM=; b=BpHuqMdC9VZJPHfRnu3au5rmvQwlyeehvI6tgSYGcMR+BAq7aOFcVUSybzIkrGolwQ UFGq1Hs/Wsf0iJi6MkyW+DJri6sDlET0rJaF6hGvIoCysPSmVQzq08inWt4XeW3c/ktC 6mR+iWMYUd+P2oQnSnnp/ikQwcuXJ/KV4aA9fZTCDE5qFnRmkPkU2yfNr6xunMn/PRYc bfvGbhbDWXOm2fOGO8Q1TVl//N8P+ULMkzmpeB/kMl2tJ+WGHhWmt7fmCyCO+iWg0S6u KflT1zYnwb4shbhVkrqnsLW7Ij9CzdlNYGGm3iOOUYQDn7gDX5PdafQ5VJYTJ91sOz3z f4jA== ARC-Authentication-Results: i=2; mx.google.com; dkim=pass header.i=@amd.com header.s=selector1 header.b=rUQ94M5i; arc=pass (i=1 spf=pass spfdomain=amd.com dmarc=pass fromdomain=amd.com); spf=pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org; dmarc=pass (p=QUARANTINE sp=QUARANTINE dis=NONE) header.from=amd.com Received: from out1.vger.email (out1.vger.email. [2620:137:e000::1:20]) by mx.google.com with ESMTP id i13-20020a17090639cd00b007ade4c97618si837145eje.930.2022.11.24.09.04.49; Thu, 24 Nov 2022 09:05:13 -0800 (PST) Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) client-ip=2620:137:e000::1:20; Authentication-Results: mx.google.com; dkim=pass header.i=@amd.com header.s=selector1 header.b=rUQ94M5i; arc=pass (i=1 spf=pass spfdomain=amd.com dmarc=pass fromdomain=amd.com); spf=pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org; dmarc=pass (p=QUARANTINE sp=QUARANTINE dis=NONE) header.from=amd.com Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S229706AbiKXRDG (ORCPT + 99 others); Thu, 24 Nov 2022 12:03:06 -0500 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:59104 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S229676AbiKXRCv (ORCPT ); Thu, 24 Nov 2022 12:02:51 -0500 Received: from NAM10-DM6-obe.outbound.protection.outlook.com (mail-dm6nam10on2073.outbound.protection.outlook.com [40.107.93.73]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 7E35828E30; Thu, 24 Nov 2022 09:02:48 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; s=arcselector9901; d=microsoft.com; cv=none; b=JyxiBnuGKhUW94Kowowl24GGVb1wO7F25fGFGgmX+OBx6pnkXMom9DovGFZH9lQL0X1/SJt28nLDxTMtkTdvzJUpGOpzdkS1LXzjJXlqe7WQeniAEmHGo5UYQff2Ss+o4/rRdLUvUsPjOCwwHVa/gvE2QJNwAH+6g43A1RnXOf1NMjgiKfwOjgO/CwWkbybq1b6Itb6qzSC489RlQF/BUdHkVYMgFD23u0yKQ5Zx8r9koSiVLcj2fLRd8EZD6vLu5kkCKf6ZF6qoin9+27QNnlSzH62tRK/jsTOEHL3K263w1/GPwo5TYmFoeHsJQSn0NNSftXe7PIn8220+Jkn5ZQ== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=microsoft.com; s=arcselector9901; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-AntiSpam-MessageData-ChunkCount:X-MS-Exchange-AntiSpam-MessageData-0:X-MS-Exchange-AntiSpam-MessageData-1; bh=a9E5jl5WbHOb0/upQL3rnlHQsW50EnCihMxYedW5nKM=; b=X5M6S7GL8I/eLeLVkl2aVmKzLMmCPHQvp8SK6ndc1MiaMuJxieo4uZSddnQUgOpNOt4g1tAYqj31nXQRq3o/zdzUN+5tBqQzlPq7wiiN50M4Un2YC+g1Ufrgj6d3Yxu7IF0R2PDjsQT63UH9Rr65VOAlzn7yynGoCrQgBEqjcC6QACKT0BqL7JhwNdsJi359PuomR7hzuiPB8spSTY+VuKhQQxmU1GaWfbuRg6stps2b6iV1tCfaIROW6nAl41F2Bb7Ap4ft4X/09aVGCFxvph1vXnabB4DvQqWd0Ip3rtipddhlxVqYB1LGTU1hwb7itiW8aUq/l+N68xcEoiw5MA== ARC-Authentication-Results: i=1; mx.microsoft.com 1; spf=pass (sender ip is 165.204.84.17) smtp.rcpttodomain=lwn.net smtp.mailfrom=amd.com; dmarc=pass (p=quarantine sp=quarantine pct=100) action=none header.from=amd.com; dkim=none (message not signed); arc=none DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=amd.com; s=selector1; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-SenderADCheck; bh=a9E5jl5WbHOb0/upQL3rnlHQsW50EnCihMxYedW5nKM=; b=rUQ94M5iKGGUyjVpawC+cT5Zv9MIieylkZm8lC8LBEIQB7lZhJvNMXdmxjyysNiroJaKV04iRNhwlaDBe65UtzxeKilCkLMscLvkGAiuVEbHSYCy11yy+NZZWrcYnzy8be6u9+Gz4t1wr4TMfdAHhPJ7cg7HUmGhBymDaMoH6wE= Received: from DM5PR07CA0069.namprd07.prod.outlook.com (2603:10b6:4:ad::34) by DM6PR12MB4169.namprd12.prod.outlook.com (2603:10b6:5:215::22) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.5857.19; Thu, 24 Nov 2022 17:02:46 +0000 Received: from DM6NAM11FT004.eop-nam11.prod.protection.outlook.com (2603:10b6:4:ad:cafe::95) by DM5PR07CA0069.outlook.office365.com (2603:10b6:4:ad::34) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.5857.18 via Frontend Transport; Thu, 24 Nov 2022 17:02:46 +0000 X-MS-Exchange-Authentication-Results: spf=pass (sender IP is 165.204.84.17) smtp.mailfrom=amd.com; dkim=none (message not signed) header.d=none;dmarc=pass action=none header.from=amd.com; Received-SPF: Pass (protection.outlook.com: domain of amd.com designates 165.204.84.17 as permitted sender) receiver=protection.outlook.com; client-ip=165.204.84.17; helo=SATLEXMB03.amd.com; pr=C Received: from SATLEXMB03.amd.com (165.204.84.17) by DM6NAM11FT004.mail.protection.outlook.com (10.13.172.217) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256) id 15.20.5834.8 via Frontend Transport; Thu, 24 Nov 2022 17:02:45 +0000 Received: from SATLEXMB05.amd.com (10.181.40.146) by SATLEXMB03.amd.com (10.181.40.144) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256) id 15.1.2375.34; Thu, 24 Nov 2022 11:02:45 -0600 Received: from SATLEXMB04.amd.com (10.181.40.145) by SATLEXMB05.amd.com (10.181.40.146) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256) id 15.1.2375.34; Thu, 24 Nov 2022 11:02:44 -0600 Received: from iron-maiden.amd.com (10.180.168.240) by SATLEXMB04.amd.com (10.181.40.145) with Microsoft SMTP Server id 15.1.2375.34 via Frontend Transport; Thu, 24 Nov 2022 11:02:44 -0600 From: Carlos Bilbao To: , , CC: , , , Carlos Bilbao Subject: [PATCH 2/6] docs: Retire old resources from kernel-docs.rst Date: Thu, 24 Nov 2022 11:02:38 -0600 Message-ID: <20221124170242.1892751-3-carlos.bilbao@amd.com> X-Mailer: git-send-email 2.34.1 In-Reply-To: <20221124170242.1892751-1-carlos.bilbao@amd.com> References: <20221124170242.1892751-1-carlos.bilbao@amd.com> MIME-Version: 1.0 X-EOPAttributedMessage: 0 X-MS-PublicTrafficType: Email X-MS-TrafficTypeDiagnostic: DM6NAM11FT004:EE_|DM6PR12MB4169:EE_ X-MS-Office365-Filtering-Correlation-Id: 3fdde30f-50f4-4066-d44c-08dace3db57a X-MS-Exchange-SenderADCheck: 1 X-MS-Exchange-AntiSpam-Relay: 0 X-Microsoft-Antispam: BCL:0; X-Microsoft-Antispam-Message-Info: 8AE/xMPcxF9VgUCl7im4afWJ6epD5/2Gp5/H5kqYTTGbM6isWFKhWmolFC3qF7viilYqrva9du8nLXqm4KxByuOvcW86gTmKwGnM11RIhokr8movtWZ6v+7wgOK39Wi6JNLP+0Up4+Bn1yhi3eve6fKyeXoKx2MVocKORtHjfyYVXwU2gD4IiB5OIkfmXVLqP2MrImk57/VKbv9qSsKHmYnYgckU6MOZpattOIBNhyX4shi0FndsRFAixQ3CKx84G79ZFRqSKfMjo5wvDYqpcB1fLYLXtdvRbrXfo/LC1Sj+bSBualmMO2xo1lMGqTVo+G+gNKYj+UcAdA7jE0KZgoZ92a99UTdyLvnOrI/ZeEoaNpbkuC46lnIJQs9C/VZjJJzC5Kv4bFpYBIGact9qmUMU9aFU80K4TpsONH4yWnoM91TRbHt8uCX1IwI2vc/aeTuBANTJ/OwtlcmK2mmbrzsfiezDzuf7kd1ZWgLzr0ag98YjBRElJo3KPjt4jkMuGyTIoYpbMXjOW+L15wrRqz+ZNespHDobiRRRyIuK6ytkAVXHP0kkUGKccjOH+MY85V3+YxUAxT1TOr5E/WOVGd2Mbhde0zMo8Wy5qMwqm7mkn4aWatzsWNAEEVt2/NEAg+oC7Bi1mHR3VQS/IxfG19NqyShHhdhmXVR/+UHV1A3pH1kb112QU3/5wtljwSgGo2qg7GgDDwp0REl9iV8zlESH/bPN0stO8ps6rzEWPeJ6ycSf/h3ZFk6FOvCxovHupyXK2rctA3IW5sUCeEbi1Egp4/3+9X9OoxGTRFhY0SSVegYNvpcr8vl/MqWKN2pmvxoGj+tGhm04mnLwzKFkCA== X-Forefront-Antispam-Report: CIP:165.204.84.17;CTRY:US;LANG:en;SCL:1;SRV:;IPV:CAL;SFV:NSPM;H:SATLEXMB03.amd.com;PTR:InfoDomainNonexistent;CAT:NONE;SFS:(13230022)(4636009)(39860400002)(376002)(346002)(396003)(136003)(451199015)(36840700001)(40470700004)(46966006)(66899015)(66574015)(47076005)(83380400001)(336012)(426003)(40460700003)(86362001)(7696005)(54906003)(110136005)(966005)(6666004)(40480700001)(81166007)(356005)(15188155005)(36756003)(16799955002)(82740400003)(82310400005)(36860700001)(1076003)(2616005)(186003)(30864003)(44832011)(5660300002)(26005)(478600001)(70206006)(8676002)(316002)(70586007)(2906002)(41300700001)(4326008)(8936002)(36900700001)(19623215001);DIR:OUT;SFP:1101; X-OriginatorOrg: amd.com X-MS-Exchange-CrossTenant-OriginalArrivalTime: 24 Nov 2022 17:02:45.8618 (UTC) X-MS-Exchange-CrossTenant-Network-Message-Id: 3fdde30f-50f4-4066-d44c-08dace3db57a X-MS-Exchange-CrossTenant-Id: 3dd8961f-e488-4e60-8e11-a82d994e183d X-MS-Exchange-CrossTenant-OriginalAttributedTenantConnectingIp: TenantId=3dd8961f-e488-4e60-8e11-a82d994e183d;Ip=[165.204.84.17];Helo=[SATLEXMB03.amd.com] X-MS-Exchange-CrossTenant-AuthSource: DM6NAM11FT004.eop-nam11.prod.protection.outlook.com X-MS-Exchange-CrossTenant-AuthAs: Anonymous X-MS-Exchange-CrossTenant-FromEntityHeader: HybridOnPrem X-MS-Exchange-Transport-CrossTenantHeadersStamped: DM6PR12MB4169 X-Spam-Status: No, score=-2.1 required=5.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID,DKIM_VALID_AU,DKIM_VALID_EF,RCVD_IN_DNSWL_NONE, RCVD_IN_MSPIKE_H2,SPF_HELO_PASS,SPF_PASS autolearn=ham autolearn_force=no version=3.4.6 X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on lindbergh.monkeyblade.net Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org X-getmail-retrieved-from-mailbox: =?utf-8?q?INBOX?= X-GMAIL-THRID: =?utf-8?q?1750397892649735878?= X-GMAIL-MSGID: =?utf-8?q?1750397892649735878?= Remove outdated or obsolete resources from process/kernel-docs.rst, with the exception of foundational material. Update information regarding LWN.net. See Link below for further context. Link: https://lore.kernel.org/lkml/093907af-2e4e-d232-1eb0-7331ff2b9320@amd.com/ Signed-off-by: Carlos Bilbao --- Documentation/process/kernel-docs.rst | 465 +------------------------- 1 file changed, 7 insertions(+), 458 deletions(-) diff --git a/Documentation/process/kernel-docs.rst b/Documentation/process/kernel-docs.rst index 5e533c827cef..d66ac26e2f27 100644 --- a/Documentation/process/kernel-docs.rst +++ b/Documentation/process/kernel-docs.rst @@ -28,7 +28,9 @@ All documents are cataloged with the following fields: the document's .. note:: The documents on each section of this document are ordered by its - published date, from the newest to the oldest. + published date, from the newest to the oldest. The maintainer(s) should + periodically retire resources as they become obsolte or outdated; with + the exception of foundational books. Docs at the Linux Kernel tree ----------------------------- @@ -58,24 +60,6 @@ On-line docs a brief description of some of the acronyms and terms you may hear during discussion of the Linux kernel". - * Title: **Tracing the Way of Data in a TCP Connection through the Linux Kernel** - - :Author: Richard Sailer - :URL: https://archive.org/details/linux_kernel_data_flow_short_paper - :Date: 2016 - :Keywords: Linux Kernel Networking, TCP, tracing, ftrace - :Description: A seminar paper explaining ftrace and how to use it for - understanding linux kernel internals, - illustrated at tracing the way of a TCP packet through the kernel. - :Abstract: *This short paper outlines the usage of ftrace a tracing framework - as a tool to understand a running Linux system. - Having obtained a trace-log a kernel hacker can read and understand - source code more determined and with context. - In a detailed example this approach is demonstrated in tracing - and the way of data in a TCP Connection through the kernel. - Finally this trace-log is used as base for more a exact conceptual - exploration and description of the Linux TCP/IP implementation.* - * Title: **The Linux Kernel Module Programming Guide** :Author: Peter Jay Salzman, Michael Burian, Ori Pomerantz, Bob Mottram, @@ -88,380 +72,9 @@ On-line docs programming. Lots of examples. Currently the new version is being actively maintained at https://github.com/sysprog21/lkmpg. - * Title: **On submitting kernel Patches** - - :Author: Andi Kleen - :URL: http://halobates.de/on-submitting-kernel-patches.pdf - :Date: 2008 - :Keywords: patches, review process, types of submissions, basic rules, case studies - :Description: This paper gives several experience values on what types of patches - there are and how likely they get merged. - :Abstract: - [...]. This paper examines some common problems for - submitting larger changes and some strategies to avoid problems. - - * Title: **Linux Device Drivers, Third Edition** - - :Author: Jonathan Corbet, Alessandro Rubini, Greg Kroah-Hartman - :URL: https://lwn.net/Kernel/LDD3/ - :Date: 2005 - :Description: A 600-page book covering the (2.6.10) driver - programming API and kernel hacking in general. Available under the - Creative Commons Attribution-ShareAlike 2.0 license. - :note: You can also :ref:`purchase a copy from O'Reilly or elsewhere `. - - * Title: **Writing an ALSA Driver** - - :Author: Takashi Iwai - :URL: https://www.kernel.org/doc/html/latest/sound/kernel-api/writing-an-alsa-driver.html - :Date: 2005 - :Keywords: ALSA, sound, soundcard, driver, lowlevel, hardware. - :Description: Advanced Linux Sound Architecture for developers, - both at kernel and user-level sides. ALSA is the Linux kernel - sound architecture in the 2.6 kernel version. - - * Title: **Linux PCMCIA Programmer's Guide** - - :Author: David Hinds. - :URL: http://pcmcia-cs.sourceforge.net/ftp/doc/PCMCIA-PROG.html - :Date: 2003 - :Keywords: PCMCIA. - :Description: "This document describes how to write kernel device - drivers for the Linux PCMCIA Card Services interface. It also - describes how to write user-mode utilities for communicating with - Card Services. - - * Title: **How NOT to write kernel drivers** - - :Author: Arjan van de Ven. - :URL: https://landley.net/kdocs/ols/2002/ols2002-pages-545-555.pdf - :Date: 2002 - :Keywords: driver. - :Description: Programming bugs and Do-nots in kernel driver development - :Abstract: *Quit a few tutorials, articles and books give an introduction - on how to write Linux kernel drivers. Unfortunately the things one - should NOT do in Linux kernel code is either only a minor appendix - or, more commonly, completely absent. This paper tries to briefly touch - the areas in which the most common and serious bugs and do-nots are - encountered.* - - * Title: **Global spinlock list and usage** - - :Author: Rick Lindsley. - :URL: http://lse.sourceforge.net/lockhier/global-spin-lock - :Date: 2001 - :Keywords: spinlock. - :Description: This is an attempt to document both the existence and - usage of the spinlocks in the Linux 2.4.5 kernel. Comprehensive - list of spinlocks showing when they are used, which functions - access them, how each lock is acquired, under what conditions it - is held, whether interrupts can occur or not while it is held... - - * Title: **A Linux vm README** - - :Author: Kanoj Sarcar. - :URL: http://kos.enix.org/pub/linux-vmm.html - :Date: 2001 - :Keywords: virtual memory, mm, pgd, vma, page, page flags, page - cache, swap cache, kswapd. - :Description: Telegraphic, short descriptions and definitions - relating the Linux virtual memory implementation. - - * Title: **Video4linux Drivers, Part 1: Video-Capture Device** - - :Author: Alan Cox. - :URL: http://www.linux-mag.com/id/406 - :Date: 2000 - :Keywords: video4linux, driver, video capture, capture devices, - camera driver. - :Description: The title says it all. - - * Title: **Video4linux Drivers, Part 2: Video-capture Devices** - - :Author: Alan Cox. - :URL: http://www.linux-mag.com/id/429 - :Date: 2000 - :Keywords: video4linux, driver, video capture, capture devices, - camera driver, control, query capabilities, capability, facility. - :Description: The title says it all. - - * Title: **Linux IP Networking. A Guide to the Implementation and Modification of the Linux Protocol Stack.** - - :Author: Glenn Herrin. - :URL: http://www.cs.unh.edu/cnrg/gherrin - :Date: 2000 - :Keywords: network, networking, protocol, IP, UDP, TCP, connection, - socket, receiving, transmitting, forwarding, routing, packets, - modules, /proc, sk_buff, FIB, tags. - :Description: Excellent paper devoted to the Linux IP Networking, - explaining anything from the kernel's to the user space - configuration tools' code. Very good to get a general overview of - the kernel networking implementation and understand all steps - packets follow from the time they are received at the network - device till they are delivered to applications. The studied kernel - code is from 2.2.14 version. Provides code for a working packet - dropper example. - - * Title: **How To Make Sure Your Driver Will Work On The Power Macintosh** - - :Author: Paul Mackerras. - :URL: http://www.linux-mag.com/id/261 - :Date: 1999 - :Keywords: Mac, Power Macintosh, porting, drivers, compatibility. - :Description: The title says it all. - - * Title: **An Introduction to SCSI Drivers** - - :Author: Alan Cox. - :URL: http://www.linux-mag.com/id/284 - :Date: 1999 - :Keywords: SCSI, device, driver. - :Description: The title says it all. - - * Title: **Advanced SCSI Drivers And Other Tales** - - :Author: Alan Cox. - :URL: http://www.linux-mag.com/id/307 - :Date: 1999 - :Keywords: SCSI, device, driver, advanced. - :Description: The title says it all. - - * Title: **Writing Linux Mouse Drivers** - - :Author: Alan Cox. - :URL: http://www.linux-mag.com/id/330 - :Date: 1999 - :Keywords: mouse, driver, gpm. - :Description: The title says it all. - - * Title: **More on Mouse Drivers** - - :Author: Alan Cox. - :URL: http://www.linux-mag.com/id/356 - :Date: 1999 - :Keywords: mouse, driver, gpm, races, asynchronous I/O. - :Description: The title still says it all. - - * Title: **Writing Video4linux Radio Driver** - - :Author: Alan Cox. - :URL: http://www.linux-mag.com/id/381 - :Date: 1999 - :Keywords: video4linux, driver, radio, radio devices. - :Description: The title says it all. - - * Title: **I/O Event Handling Under Linux** - - :Author: Richard Gooch. - :URL: https://web.mit.edu/~yandros/doc/io-events.html - :Date: 1999 - :Keywords: IO, I/O, select(2), poll(2), FDs, aio_read(2), readiness - event queues. - :Description: From the Introduction: "I/O Event handling is about - how your Operating System allows you to manage a large number of - open files (file descriptors in UNIX/POSIX, or FDs) in your - application. You want the OS to notify you when FDs become active - (have data ready to be read or are ready for writing). Ideally you - want a mechanism that is scalable. This means a large number of - inactive FDs cost very little in memory and CPU time to manage". - - * Title: **(nearly) Complete Linux Loadable Kernel Modules. The definitive guide for hackers, virus coders and system administrators.** - - :Author: pragmatic/THC. - :URL: http://packetstormsecurity.org/docs/hack/LKM_HACKING.html - :Date: 1999 - :Keywords: syscalls, intercept, hide, abuse, symbol table. - :Description: Interesting paper on how to abuse the Linux kernel in - order to intercept and modify syscalls, make - files/directories/processes invisible, become root, hijack ttys, - write kernel modules based virus... and solutions for admins to - avoid all those abuses. - :Notes: For 2.0.x kernels. Gives guidances to port it to 2.2.x - kernels. - - * Name: **Linux Virtual File System** - - :Author: Peter J. Braam. - :URL: http://www.coda.cs.cmu.edu/doc/talks/linuxvfs/ - :Date: 1998 - :Keywords: slides, VFS, inode, superblock, dentry, dcache. - :Description: Set of slides, presumably from a presentation on the - Linux VFS layer. Covers version 2.1.x, with dentries and the - dcache. - - * Title: **The Venus kernel interface** - - :Author: Peter J. Braam. - :URL: http://www.coda.cs.cmu.edu/doc/html/kernel-venus-protocol.html - :Date: 1998 - :Keywords: coda, filesystem, venus, cache manager. - :Description: "This document describes the communication between - Venus and kernel level file system code needed for the operation - of the Coda filesystem. This version document is meant to describe - the current interface (version 1.0) as well as improvements we - envisage". - - * Title: **Design and Implementation of the Second Extended Filesystem** - - :Author: Rémy Card, Theodore Ts'o, Stephen Tweedie. - :URL: https://web.mit.edu/tytso/www/linux/ext2intro.html - :Date: 1998 - :Keywords: ext2, linux fs history, inode, directory, link, devices, - VFS, physical structure, performance, benchmarks, ext2fs library, - ext2fs tools, e2fsck. - :Description: Paper written by three of the top ext2 hackers. - Covers Linux filesystems history, ext2 motivation, ext2 features, - design, physical structure on disk, performance, benchmarks, - e2fsck's passes description... A must read! - :Notes: This paper was first published in the Proceedings of the - First Dutch International Symposium on Linux, ISBN 90-367-0385-9. - - * Title: **The Linux RAID-1, 4, 5 Code** - - :Author: Ingo Molnar, Gadi Oxman and Miguel de Icaza. - :URL: http://www.linuxjournal.com/article.php?sid=2391 - :Date: 1997 - :Keywords: RAID, MD driver. - :Description: Linux Journal Kernel Korner article. - :Abstract: *A description of the implementation of the RAID-1, - RAID-4 and RAID-5 personalities of the MD device driver in the - Linux kernel, providing users with high performance and reliable, - secondary-storage capability using software*. - - * Title: **Linux Kernel Hackers' Guide** - - :Author: Michael K. Johnson. - :URL: https://www.tldp.org/LDP/khg/HyperNews/get/khg.html - :Date: 1997 - :Keywords: device drivers, files, VFS, kernel interface, character vs - block devices, hardware interrupts, scsi, DMA, access to user memory, - memory allocation, timers. - :Description: A guide designed to help you get up to speed on the - concepts that are not intuitively obvious, and to document the internal - structures of Linux. - - * Title: **Dynamic Kernels: Modularized Device Drivers** - - :Author: Alessandro Rubini. - :URL: http://www.linuxjournal.com/article.php?sid=1219 - :Date: 1996 - :Keywords: device driver, module, loading/unloading modules, - allocating resources. - :Description: Linux Journal Kernel Korner article. - :Abstract: *This is the first of a series of four articles - co-authored by Alessandro Rubini and Georg Zezchwitz which present - a practical approach to writing Linux device drivers as kernel - loadable modules. This installment presents an introduction to the - topic, preparing the reader to understand next month's - installment*. - - * Title: **Dynamic Kernels: Discovery** - - :Author: Alessandro Rubini. - :URL: http://www.linuxjournal.com/article.php?sid=1220 - :Date: 1996 - :Keywords: character driver, init_module, clean_up module, - autodetection, mayor number, minor number, file operations, - open(), close(). - :Description: Linux Journal Kernel Korner article. - :Abstract: *This article, the second of four, introduces part of - the actual code to create custom module implementing a character - device driver. It describes the code for module initialization and - cleanup, as well as the open() and close() system calls*. - - * Title: **The Devil's in the Details** - - :Author: Georg v. Zezschwitz and Alessandro Rubini. - :URL: http://www.linuxjournal.com/article.php?sid=1221 - :Date: 1996 - :Keywords: read(), write(), select(), ioctl(), blocking/non - blocking mode, interrupt handler. - :Description: Linux Journal Kernel Korner article. - :Abstract: *This article, the third of four on writing character - device drivers, introduces concepts of reading, writing, and using - ioctl-calls*. - - * Title: **Dissecting Interrupts and Browsing DMA** - - :Author: Alessandro Rubini and Georg v. Zezschwitz. - :URL: https://www.linuxjournal.com/article.php?sid=1222 - :Date: 1996 - :Keywords: interrupts, irqs, DMA, bottom halves, task queues. - :Description: Linux Journal Kernel Korner article. - :Abstract: *This is the fourth in a series of articles about - writing character device drivers as loadable kernel modules. This - month, we further investigate the field of interrupt handling. - Though it is conceptually simple, practical limitations and - constraints make this an ''interesting'' part of device driver - writing, and several different facilities have been provided for - different situations. We also investigate the complex topic of - DMA*. - - * Title: **Device Drivers Concluded** - - :Author: Georg v. Zezschwitz. - :URL: https://www.linuxjournal.com/article.php?sid=1287 - :Date: 1996 - :Keywords: address spaces, pages, pagination, page management, - demand loading, swapping, memory protection, memory mapping, mmap, - virtual memory areas (VMAs), vremap, PCI. - :Description: Finally, the above turned out into a five articles - series. This latest one's introduction reads: "This is the last of - five articles about character device drivers. In this final - section, Georg deals with memory mapping devices, beginning with - an overall description of the Linux memory management concepts". - - * Title: **Network Buffers And Memory Management** - - :Author: Alan Cox. - :URL: https://www.linuxjournal.com/article.php?sid=1312 - :Date: 1996 - :Keywords: sk_buffs, network devices, protocol/link layer - variables, network devices flags, transmit, receive, - configuration, multicast. - :Description: Linux Journal Kernel Korner. - :Abstract: *Writing a network device driver for Linux is fundamentally - simple---most of the complexity (other than talking to the - hardware) involves managing network packets in memory*. - - * Title: **Analysis of the Ext2fs structure** - - :Author: Louis-Dominique Dubeau. - :URL: https://teaching.csse.uwa.edu.au/units/CITS2002/fs-ext2/ - :Date: 1994 - :Keywords: ext2, filesystem, ext2fs. - :Description: Description of ext2's blocks, directories, inodes, - bitmaps, invariants... - Published books --------------- - * Title: **Linux Treiber entwickeln** - - :Author: Jürgen Quade, Eva-Katharina Kunst - :Publisher: dpunkt.verlag - :Date: Oct 2015 (4th edition) - :Pages: 688 - :ISBN: 978-3-86490-288-8 - :Note: German. The third edition from 2011 is - much cheaper and still quite up-to-date. - - * Title: **Linux Kernel Networking: Implementation and Theory** - - :Author: Rami Rosen - :Publisher: Apress - :Date: December 22, 2013 - :Pages: 648 - :ISBN: 978-1430261964 - - * Title: **Embedded Linux Primer: A practical Real-World Approach, 2nd Edition** - - :Author: Christopher Hallinan - :Publisher: Pearson - :Date: November, 2010 - :Pages: 656 - :ISBN: 978-0137017836 - * Title: **Linux Kernel Development, 3rd Edition** :Author: Robert Love @@ -469,14 +82,7 @@ Published books :Date: July, 2010 :Pages: 440 :ISBN: 978-0672329463 - - * Title: **Essential Linux Device Drivers** - - :Author: Sreekrishnan Venkateswaran - :Published: Prentice Hall - :Date: April, 2008 - :Pages: 744 - :ISBN: 978-0132396554 + :Notes: Foundational book .. _ldd3_published: @@ -487,68 +93,10 @@ Published books :Date: 2005 :Pages: 636 :ISBN: 0-596-00590-3 - :Notes: Further information in + :Notes: Foundational book. Further information in http://www.oreilly.com/catalog/linuxdrive3/ PDF format, URL: https://lwn.net/Kernel/LDD3/ - * Title: **Linux Kernel Internals** - - :Author: Michael Beck - :Publisher: Addison-Wesley - :Date: 1997 - :ISBN: 0-201-33143-8 (second edition) - - * Title: **Programmation Linux 2.0 API systeme et fonctionnement du noyau** - - :Author: Remy Card, Eric Dumas, Franck Mevel - :Publisher: Eyrolles - :Date: 1997 - :Pages: 520 - :ISBN: 2-212-08932-5 - :Notes: French - - * Title: **The Design and Implementation of the 4.4 BSD UNIX Operating System** - - :Author: Marshall Kirk McKusick, Keith Bostic, Michael J. Karels, - John S. Quarterman - :Publisher: Addison-Wesley - :Date: 1996 - :ISBN: 0-201-54979-4 - - * Title: **Unix internals -- the new frontiers** - - :Author: Uresh Vahalia - :Publisher: Prentice Hall - :Date: 1996 - :Pages: 600 - :ISBN: 0-13-101908-2 - - * Title: **Programming for the real world - POSIX.4** - - :Author: Bill O. Gallmeister - :Publisher: O'Reilly & Associates, Inc - :Date: 1995 - :Pages: 552 - :ISBN: I-56592-074-0 - :Notes: Though not being directly about Linux, Linux aims to be - POSIX. Good reference. - - * Title: **UNIX Systems for Modern Architectures: Symmetric Multiprocessing and Caching for Kernel Programmers** - - :Author: Curt Schimmel - :Publisher: Addison Wesley - :Date: June, 1994 - :Pages: 432 - :ISBN: 0-201-63338-8 - - * Title: **The Design and Implementation of the 4.3 BSD UNIX Operating System** - - :Author: Samuel J. Leffler, Marshall Kirk McKusick, Michael J - Karels, John S. Quarterman - :Publisher: Addison-Wesley - :Date: 1989 (reprinted with corrections on October, 1990) - :ISBN: 0-201-06196-1 - * Title: **The Design of the UNIX Operating System** :Author: Maurice J. Bach @@ -556,6 +104,7 @@ Published books :Date: 1986 :Pages: 471 :ISBN: 0-13-201757-1 + :Notes: Foundational book Miscellaneous ------------- @@ -574,7 +123,7 @@ Miscellaneous :Keywords: latest kernel news. :Description: The title says it all. There's a fixed kernel section summarizing developers' work, bug fixes, new features and versions - produced during the week. Published every Thursday. + produced during the week. * Name: **The home page of Linux-MM** From patchwork Thu Nov 24 17:02:39 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Carlos Bilbao X-Patchwork-Id: 25639 Return-Path: Delivered-To: ouuuleilei@gmail.com Received: by 2002:adf:f944:0:0:0:0:0 with SMTP id q4csp3511511wrr; Thu, 24 Nov 2022 09:05:22 -0800 (PST) X-Google-Smtp-Source: AA0mqf4Hg1UAjY3Dtbkx9p0P7x9xZigefZE2wzSm8/EgNinYFRrI/JsVQ8PuuEABCyphXCtznr9H X-Received: by 2002:a17:906:c404:b0:7ad:821f:a3e5 with SMTP id u4-20020a170906c40400b007ad821fa3e5mr12703327ejz.554.1669309521982; Thu, 24 Nov 2022 09:05:21 -0800 (PST) ARC-Seal: i=2; a=rsa-sha256; t=1669309521; cv=pass; d=google.com; s=arc-20160816; b=FOlQwm7IxxCC5Zx0TU/GHtcv46tHB5wbFwJ7tSEsdE/arZQrx7rh9Ob+BJ2xOe0O7T ayUdHEvX9X/iEARTNOeewg3ucOeDOBKL3YCkuAgy3nfjyrx5pqwg8G4IoLk4uP47DfiF DK5kqn9g5A6kH0AWFBqx+e2cyd6nZQezbbAIewHDmrltZPLDYFQ3OvWwcVopHF+P0kA4 4iLK+DKjOdCOs7v56/j8hLUl6QfzJVGdYCxQu2tXnM0FOKhYTBGkGtjpNa6uLzzkuY+H VUNF35JgOImXArJtG6/TaJ32AX3lUi8mfn4nAU6pymn0Lzdg1fBCCRBMMKynwp/85idE 6aKw== ARC-Message-Signature: i=2; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=list-id:precedence:content-transfer-encoding:mime-version :references:in-reply-to:message-id:date:subject:cc:to:from :dkim-signature; bh=w7Z6vC4vyHthNCtaqY18LDj/TklJNDVKOARGNkN2GaU=; b=YAL2bkuKHivvnl0jnXaOW3d0Nj2YGEWJOWog8m2vNY9QrO0qoobhy63OnVdEQ9pwSC pz4lpBoxb8AYDfTP6NIVXaOLv8HbUOMAccFNWrMgi4hFDTa/cOgOSMdk8lRkh9LBBJqo ug/Y8S2YYSKbNbbFL1uZRp8FeIyh+pyRUuM35ZW9Sh1k4sURHF3j6fupXY1Ro9xlQvlp 0BthgqqpuAsQsR0Q9lvWAYrw9yn1jZeVdzUBJzHxtvfW0xxYzjJ+jzFxGtYcysTMrpv7 GyIyOE9MH62MzlWn/lOQr8Ted7QxnLGsjsDYQiJ+Mqf+Ef25qefj1fcM7ji2OrUfXohK JBMg== ARC-Authentication-Results: i=2; mx.google.com; dkim=pass header.i=@amd.com header.s=selector1 header.b=qPm6SGLW; arc=pass (i=1 spf=pass spfdomain=amd.com dmarc=pass fromdomain=amd.com); spf=pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org; dmarc=pass (p=QUARANTINE sp=QUARANTINE dis=NONE) header.from=amd.com Received: from out1.vger.email (out1.vger.email. [2620:137:e000::1:20]) by mx.google.com with ESMTP id xf9-20020a17090731c900b0078d459a1ce9si813466ejb.693.2022.11.24.09.04.56; Thu, 24 Nov 2022 09:05:21 -0800 (PST) Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) client-ip=2620:137:e000::1:20; Authentication-Results: mx.google.com; dkim=pass header.i=@amd.com header.s=selector1 header.b=qPm6SGLW; arc=pass (i=1 spf=pass spfdomain=amd.com dmarc=pass fromdomain=amd.com); spf=pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org; dmarc=pass (p=QUARANTINE sp=QUARANTINE dis=NONE) header.from=amd.com Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S229455AbiKXRC6 (ORCPT + 99 others); Thu, 24 Nov 2022 12:02:58 -0500 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:59018 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S229640AbiKXRCt (ORCPT ); Thu, 24 Nov 2022 12:02:49 -0500 Received: from NAM02-BN1-obe.outbound.protection.outlook.com (mail-bn1nam02on2043.outbound.protection.outlook.com [40.107.212.43]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 1FEAD2B1BB; Thu, 24 Nov 2022 09:02:49 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; s=arcselector9901; d=microsoft.com; cv=none; b=Pl4kYrQrHORdw5cwvz+dslxaBuDsGlyBynUYBpvfmhPCphGwi9JKXkGaSnQpeefSVDFTyajx4oqEtz8P1kNtoL8xzLEfKTbzUY98x1Hxg5RY4zOjqzTspQ9IzacNXmAkNZs1qeXD4gv4clIDFSNBFoWu0VVTPmpavtsx355j2tDambVuphCi9O4XWZpA5oF7WegfSVOjtJ47BEtLO57NoL0j1+gj13PGQQ1jhlxbNmnzRsgWMQ02LFVCEQrV9grAwumaFrH993lF+7yylGh4cw+ClZPuo0pun85NknINTVUxqrf8Nu1ormYVHXmnDMucSPXosYUVC+LmEqN39LOvZg== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=microsoft.com; s=arcselector9901; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-AntiSpam-MessageData-ChunkCount:X-MS-Exchange-AntiSpam-MessageData-0:X-MS-Exchange-AntiSpam-MessageData-1; bh=w7Z6vC4vyHthNCtaqY18LDj/TklJNDVKOARGNkN2GaU=; b=PtJ/G7gTX8XzS2pyzE6quaLwkVGrQIpppOg3u7ZBBZbMnaZQZy7T52fwguBDLoH0P7yDVTJZqQPqWTOdNhsQPEOwHDoPD/1yDvXs7BN0Zcd19MEu0iSRCOqZdIL8TT+RGdfPoesIy212ko6js1ImTksTvc0egg/PoCLgOH6L62dLiVT9mnIXyDpxFUQLof1MOh6qsumT1WcVFqFshaR1qRWdYUUzIuxu7dCKMwVYrC1RuWuPL9LSZSutLFFGtNnbDwSbZR4tEUjoJW4lVT9SamnmLOC2wo2HRGp0MnEb7oK4izlWGTvyOBNNcjJH2ZCn+bbMCYH5kKhT4J1I5RPFBw== ARC-Authentication-Results: i=1; mx.microsoft.com 1; spf=pass (sender ip is 165.204.84.17) smtp.rcpttodomain=lwn.net smtp.mailfrom=amd.com; dmarc=pass (p=quarantine sp=quarantine pct=100) action=none header.from=amd.com; dkim=none (message not signed); arc=none DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=amd.com; s=selector1; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-SenderADCheck; bh=w7Z6vC4vyHthNCtaqY18LDj/TklJNDVKOARGNkN2GaU=; b=qPm6SGLWEMMgH+EQh9dCigrD1Tzmq6huid0HLPL73mvFy9GwHND6rR4NF2892wR70xYIDo1tGHVxSAx1DOSvKEkG5GsIPtn4NcQya5WpnqyiA1OOW3KwYVvjJYdYHMek4/ms2uUO6YmYgkwmH6pwB+m3z5GjOPpKYRjT463lLdY= Received: from MW4PR03CA0196.namprd03.prod.outlook.com (2603:10b6:303:b8::21) by PH7PR12MB6658.namprd12.prod.outlook.com (2603:10b6:510:211::14) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.5857.18; Thu, 24 Nov 2022 17:02:47 +0000 Received: from CO1NAM11FT059.eop-nam11.prod.protection.outlook.com (2603:10b6:303:b8:cafe::fb) by MW4PR03CA0196.outlook.office365.com (2603:10b6:303:b8::21) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.5857.19 via Frontend Transport; Thu, 24 Nov 2022 17:02:47 +0000 X-MS-Exchange-Authentication-Results: spf=pass (sender IP is 165.204.84.17) smtp.mailfrom=amd.com; dkim=none (message not signed) header.d=none;dmarc=pass action=none header.from=amd.com; Received-SPF: Pass (protection.outlook.com: domain of amd.com designates 165.204.84.17 as permitted sender) receiver=protection.outlook.com; client-ip=165.204.84.17; helo=SATLEXMB04.amd.com; pr=C Received: from SATLEXMB04.amd.com (165.204.84.17) by CO1NAM11FT059.mail.protection.outlook.com (10.13.174.160) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256) id 15.20.5857.18 via Frontend Transport; Thu, 24 Nov 2022 17:02:46 +0000 Received: from SATLEXMB06.amd.com (10.181.40.147) by SATLEXMB04.amd.com (10.181.40.145) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256) id 15.1.2375.34; Thu, 24 Nov 2022 11:02:45 -0600 Received: from SATLEXMB04.amd.com (10.181.40.145) by SATLEXMB06.amd.com (10.181.40.147) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256) id 15.1.2375.34; Thu, 24 Nov 2022 11:02:45 -0600 Received: from iron-maiden.amd.com (10.180.168.240) by SATLEXMB04.amd.com (10.181.40.145) with Microsoft SMTP Server id 15.1.2375.34 via Frontend Transport; Thu, 24 Nov 2022 11:02:45 -0600 From: Carlos Bilbao To: , , CC: , , , Carlos Bilbao Subject: [PATCH 3/6] docs: Add book to process/kernel-docs.rst Date: Thu, 24 Nov 2022 11:02:39 -0600 Message-ID: <20221124170242.1892751-4-carlos.bilbao@amd.com> X-Mailer: git-send-email 2.34.1 In-Reply-To: <20221124170242.1892751-1-carlos.bilbao@amd.com> References: <20221124170242.1892751-1-carlos.bilbao@amd.com> MIME-Version: 1.0 X-EOPAttributedMessage: 0 X-MS-PublicTrafficType: Email X-MS-TrafficTypeDiagnostic: CO1NAM11FT059:EE_|PH7PR12MB6658:EE_ X-MS-Office365-Filtering-Correlation-Id: 92f45339-59d7-4ff4-fb64-08dace3db5ef X-MS-Exchange-SenderADCheck: 1 X-MS-Exchange-AntiSpam-Relay: 0 X-Microsoft-Antispam: BCL:0; X-Microsoft-Antispam-Message-Info: RufIFUTsJKBr4txsSNtnzeBjxX9NC6QL4dgRkcbjfD40UKu9mrJu0laM9+WbeFHXFJnX3yjeWpIFsV5m4D1/VP1m6/zVO63ZEuf8jzKTS7upUml2HmIiTjc4carXStZGOh/TuWeqJAzkjVpJIgX1Ie/s5FjCRoX3HaUM0TPxq76NC00S7CiTLInc3jVGlhjPzv5Lcvsj6apqnvW3zqwLLgDGzVDf67NdY6Wa1aMCzUtHHnDJYP7QzaErnYg8d5hhkjMchOuqhfUGCBwG2qHUqGdbnbjgNRrvPKILq3YLiMVnPCLrSBoOMGt24WyAuPyFo1omE70F1m8K7Nolg5tVuW3Q4oyvABukEPXyOoUcGkI8xyvokYxAI9v3r9004ClnYAmpZhCGzPeKGdLs6cdfVpM/9+dSYov1Cew4grSh7LtH4ajbHsX8HXP5gzYjMj/BPGfC2Uh57CqgiBOqNbr/H4zXBiOqLmtsMXDKXZl3+BBdQIwQIxjlEN3jc08yDDzsAvIFjbCEE3w5rdI2pEmYMc0rNeyR0mtK1zqa3qvygvrdbt/qoar1LILbSL3rkxADF2FpY8zBsBqMdcJwzDl6vO+QhO7Vlmie9fHv37aGmqwlB+T5Xb/3Get8Sia7dPF4rzlIFZ8Gb/NttNK/RSSWAM7uIMBa9QpE3Uj9MG/7hmv+RvjlyYML84KDg7w0EUyvrKZVvsCkc1jGlaNZI8WLFp+2jttqxZl5nSga/BnRD8A= X-Forefront-Antispam-Report: CIP:165.204.84.17;CTRY:US;LANG:en;SCL:1;SRV:;IPV:CAL;SFV:NSPM;H:SATLEXMB04.amd.com;PTR:InfoDomainNonexistent;CAT:NONE;SFS:(13230022)(4636009)(396003)(346002)(136003)(39860400002)(376002)(451199015)(40470700004)(46966006)(36840700001)(36860700001)(2906002)(86362001)(8936002)(82740400003)(356005)(4744005)(81166007)(44832011)(4326008)(8676002)(41300700001)(5660300002)(40460700003)(70206006)(7696005)(6666004)(26005)(426003)(47076005)(336012)(1076003)(110136005)(316002)(2616005)(54906003)(82310400005)(478600001)(40480700001)(186003)(70586007)(36756003)(36900700001);DIR:OUT;SFP:1101; X-OriginatorOrg: amd.com X-MS-Exchange-CrossTenant-OriginalArrivalTime: 24 Nov 2022 17:02:46.5670 (UTC) X-MS-Exchange-CrossTenant-Network-Message-Id: 92f45339-59d7-4ff4-fb64-08dace3db5ef X-MS-Exchange-CrossTenant-Id: 3dd8961f-e488-4e60-8e11-a82d994e183d X-MS-Exchange-CrossTenant-OriginalAttributedTenantConnectingIp: TenantId=3dd8961f-e488-4e60-8e11-a82d994e183d;Ip=[165.204.84.17];Helo=[SATLEXMB04.amd.com] X-MS-Exchange-CrossTenant-AuthSource: CO1NAM11FT059.eop-nam11.prod.protection.outlook.com X-MS-Exchange-CrossTenant-AuthAs: Anonymous X-MS-Exchange-CrossTenant-FromEntityHeader: HybridOnPrem X-MS-Exchange-Transport-CrossTenantHeadersStamped: PH7PR12MB6658 X-Spam-Status: No, score=-2.1 required=5.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID,DKIM_VALID_AU,DKIM_VALID_EF,RCVD_IN_DNSWL_NONE, RCVD_IN_MSPIKE_H2,SPF_HELO_PASS,SPF_PASS autolearn=ham autolearn_force=no version=3.4.6 X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on lindbergh.monkeyblade.net Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org X-getmail-retrieved-from-mailbox: =?utf-8?q?INBOX?= X-GMAIL-THRID: =?utf-8?q?1750397901260478143?= X-GMAIL-MSGID: =?utf-8?q?1750397901260478143?= Include to process/kernel-docs.rst a book on Linux kernel development published in 2021 (with ISBN 978-1789953435). Signed-off-by: Carlos Bilbao --- Documentation/process/kernel-docs.rst | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/Documentation/process/kernel-docs.rst b/Documentation/process/kernel-docs.rst index d66ac26e2f27..1c6e2ab92f4e 100644 --- a/Documentation/process/kernel-docs.rst +++ b/Documentation/process/kernel-docs.rst @@ -75,6 +75,14 @@ On-line docs Published books --------------- + * Title: **Linux Kernel Programming: A Comprehensive Guide to Kernel Internals, Writing Kernel Modules, and Kernel Synchronization** + + :Author: Kaiwan N. Billimoria + :Publisher: Packt Publishing Ltd + :Date: 2021 + :Pages: 754 + :ISBN: 978-1789953435 + * Title: **Linux Kernel Development, 3rd Edition** :Author: Robert Love From patchwork Thu Nov 24 17:02:40 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Carlos Bilbao X-Patchwork-Id: 25641 Return-Path: Delivered-To: ouuuleilei@gmail.com Received: by 2002:adf:f944:0:0:0:0:0 with SMTP id q4csp3512417wrr; Thu, 24 Nov 2022 09:06:46 -0800 (PST) X-Google-Smtp-Source: AA0mqf60B8MhwjhDWNsyU8cc1AmBQS+qDodU8z4Erv4dLVOK3WEBGgrHsdcMLuSMwAy5kNaQu3cI X-Received: by 2002:a17:906:b794:b0:7ae:6450:c620 with SMTP id dt20-20020a170906b79400b007ae6450c620mr12138059ejb.270.1669309606788; Thu, 24 Nov 2022 09:06:46 -0800 (PST) ARC-Seal: i=2; a=rsa-sha256; t=1669309606; cv=pass; d=google.com; s=arc-20160816; b=mF7Z+M6fsx4rDDRkdRKy7/ue+TiO3Ea/HUSdedUBlA3cWH6NzfgcIL/IZEQd/CV521 3yz8tx+OOyUM3s07eRia8P2sFeYc2UzQO++YieIxda45+MD1rgvrDIfeEh4J+NKJD5Od qs4Ds5z9Is7JMnOeb//C8B88QIbtLIxcq3vSgaNOiu/b4HRs84FdNSEFsumqrGyZPX9h QZiXq7Bq4hl7hIL7zZdeEubH8AvH9JNUAx2RTfD1msM6sACfYaA+0Uy2OMc7XRIwZMkV aecwXeeg6DPhPm237m0E8U+doVltJyXyGpNfcKg/GDQY0/7gBjR6IMHrBa0WzI18yKtI spug== ARC-Message-Signature: i=2; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=list-id:precedence:content-transfer-encoding:mime-version :references:in-reply-to:message-id:date:subject:cc:to:from :dkim-signature; bh=vseCKTTFKFB+uzoJQf10x/BUEbwHlz76A+E0w0c6lU0=; b=K9eMRdUmLUCgAynaqjF7UFy1kOrvQArA6eg+hIJiBt5JM1Mp3I7LWI7JoUjaxxSPa7 7ynPFW5+135J2RK5pnRcE5g/6gx3QZrHHaZV8O756Sd/9a4VQKSbMlIoydlQMhkbCvSg 5KRPQdms7D1snUJpP0dsr8WDPsQEETYndw557Otdkqr3oHureeYtedMCT+T1nc2xtS5n mXMoshirl2bKyN1KPSsk7q+rxbRKpTr+iO0Q3WCUZ1zkZNSPsYhvtTCZE2BpbA7f4Oi0 OtjSQibxlHGjiFgWG9OTm97go22ece7dYDftOc8XkUbhD32yKLUzf5Hqfg8Y2xjcNbXx fpuw== ARC-Authentication-Results: i=2; mx.google.com; dkim=pass header.i=@amd.com header.s=selector1 header.b=YyZrqqWG; arc=pass (i=1 spf=pass spfdomain=amd.com dmarc=pass fromdomain=amd.com); spf=pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org; dmarc=pass (p=QUARANTINE sp=QUARANTINE dis=NONE) header.from=amd.com Received: from out1.vger.email (out1.vger.email. [2620:137:e000::1:20]) by mx.google.com with ESMTP id sd39-20020a1709076e2700b0078212b2e6e2si465860ejc.75.2022.11.24.09.06.23; Thu, 24 Nov 2022 09:06:46 -0800 (PST) Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) client-ip=2620:137:e000::1:20; Authentication-Results: mx.google.com; dkim=pass header.i=@amd.com header.s=selector1 header.b=YyZrqqWG; arc=pass (i=1 spf=pass spfdomain=amd.com dmarc=pass fromdomain=amd.com); spf=pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org; dmarc=pass (p=QUARANTINE sp=QUARANTINE dis=NONE) header.from=amd.com Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S229622AbiKXRDC (ORCPT + 99 others); Thu, 24 Nov 2022 12:03:02 -0500 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:59090 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S229675AbiKXRCv (ORCPT ); Thu, 24 Nov 2022 12:02:51 -0500 Received: from NAM10-DM6-obe.outbound.protection.outlook.com (mail-dm6nam10on2084.outbound.protection.outlook.com [40.107.93.84]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 1500B2C65C; Thu, 24 Nov 2022 09:02:50 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; s=arcselector9901; d=microsoft.com; cv=none; b=FPYeIYuvPiELxxWzcE1g/Y6Xu9ZAigkqkylx+SJIKkgRSpOBX3DxX+UQ6K/bRh8znCf4Pk73xe6CJxCTreA+DVHSYW9dXQIoeoFkz6mb4f/eABDrrz0rH51VVKrSsInG0r/vK8zjZZKay9y2dt3GDsvPl267BWsc8dcpK6hAUF3IU72X3UC+rCpu6nieTPLG55E1vQwdvXrzuJh018Tk7MaoFgQF/ByLo5pQV5rU4k+q3IWg9u8XeoHlgZ5ICtY7KANIpaXS0OR1pMVsd538gf8Mx38Jk4+D16S/RgUyxm2QCO/Sd6F1RIZLABgk4ZjHFksGyBqF3Yy3TkafNxdv+w== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=microsoft.com; s=arcselector9901; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-AntiSpam-MessageData-ChunkCount:X-MS-Exchange-AntiSpam-MessageData-0:X-MS-Exchange-AntiSpam-MessageData-1; bh=vseCKTTFKFB+uzoJQf10x/BUEbwHlz76A+E0w0c6lU0=; b=QcInqSVgd8eGe5QMe/7tnOOVNMT+KevqxIWTAtlob+OUv7zv19OEfh8JSJZ2bAatuKQntmPq539fX4ml68qewW2dCxu+CeYOXcrfsTtYHVzWcsykQrPmhgUcxNSa0LHvd+DFVFgRXUNcP7pLGl61oK1Nrgp/Reti0UId3PyVSSd/+2o2SPu/nDegWk1ZUr+LrdQl8OFjnDJ06hqkm+Gnns2bxzDG0u27Dciu4s0TqZmGfYeIRrHsYUGAQSEVSE6RFmHLeDmptutFdHFWE/z78hcY77OoxiHqbhNpnIpvRl+mdnC0xlqcEXDvVjlRvXbWeqIH35uuIzMa8dvczvnjmg== ARC-Authentication-Results: i=1; mx.microsoft.com 1; spf=pass (sender ip is 165.204.84.17) smtp.rcpttodomain=lwn.net smtp.mailfrom=amd.com; dmarc=pass (p=quarantine sp=quarantine pct=100) action=none header.from=amd.com; dkim=none (message not signed); arc=none DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=amd.com; s=selector1; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-SenderADCheck; bh=vseCKTTFKFB+uzoJQf10x/BUEbwHlz76A+E0w0c6lU0=; b=YyZrqqWGdoVmuedMGc3Z3NtDp0+cYTcDj4DGmUOUYKv/gzkiBDot/RqKrSiqt5yscWSs3067WwnMEob5AxhaWVe9Xp3UvlIlTOmVCn72ptnw+jhUxc9kGvv5WXb8n73Zmn5hR2yQNOK3+ZboPYUauc3vuQ9U1BsAP/5UcDbp3C8= Received: from MW4PR03CA0189.namprd03.prod.outlook.com (2603:10b6:303:b8::14) by BY5PR12MB4211.namprd12.prod.outlook.com (2603:10b6:a03:20f::19) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.5857.19; Thu, 24 Nov 2022 17:02:48 +0000 Received: from CO1NAM11FT059.eop-nam11.prod.protection.outlook.com (2603:10b6:303:b8:cafe::ce) by MW4PR03CA0189.outlook.office365.com (2603:10b6:303:b8::14) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.5857.19 via Frontend Transport; Thu, 24 Nov 2022 17:02:48 +0000 X-MS-Exchange-Authentication-Results: spf=pass (sender IP is 165.204.84.17) smtp.mailfrom=amd.com; dkim=none (message not signed) header.d=none;dmarc=pass action=none header.from=amd.com; Received-SPF: Pass (protection.outlook.com: domain of amd.com designates 165.204.84.17 as permitted sender) receiver=protection.outlook.com; client-ip=165.204.84.17; helo=SATLEXMB04.amd.com; pr=C Received: from SATLEXMB04.amd.com (165.204.84.17) by CO1NAM11FT059.mail.protection.outlook.com (10.13.174.160) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256) id 15.20.5857.18 via Frontend Transport; Thu, 24 Nov 2022 17:02:47 +0000 Received: from SATLEXMB05.amd.com (10.181.40.146) by SATLEXMB04.amd.com (10.181.40.145) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256) id 15.1.2375.34; Thu, 24 Nov 2022 11:02:46 -0600 Received: from SATLEXMB04.amd.com (10.181.40.145) by SATLEXMB05.amd.com (10.181.40.146) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256) id 15.1.2375.34; Thu, 24 Nov 2022 11:02:45 -0600 Received: from iron-maiden.amd.com (10.180.168.240) by SATLEXMB04.amd.com (10.181.40.145) with Microsoft SMTP Server id 15.1.2375.34 via Frontend Transport; Thu, 24 Nov 2022 11:02:45 -0600 From: Carlos Bilbao To: , , CC: , , , Carlos Bilbao Subject: [PATCH 4/6] docs: Create translations/sp_SP/process/, move submitting-patches.rst Date: Thu, 24 Nov 2022 11:02:40 -0600 Message-ID: <20221124170242.1892751-5-carlos.bilbao@amd.com> X-Mailer: git-send-email 2.34.1 In-Reply-To: <20221124170242.1892751-1-carlos.bilbao@amd.com> References: <20221124170242.1892751-1-carlos.bilbao@amd.com> MIME-Version: 1.0 X-EOPAttributedMessage: 0 X-MS-PublicTrafficType: Email X-MS-TrafficTypeDiagnostic: CO1NAM11FT059:EE_|BY5PR12MB4211:EE_ X-MS-Office365-Filtering-Correlation-Id: 03cdf752-8518-41ee-539c-08dace3db68d X-MS-Exchange-SenderADCheck: 1 X-MS-Exchange-AntiSpam-Relay: 0 X-Microsoft-Antispam: BCL:0; X-Microsoft-Antispam-Message-Info: 9sz2yR1O23dMbimaT43xPF/FGz4+H4iUbL8qjV1tc80oztm/AcPb0/aUzJY6Kx+V6VNLRrjL7ktYX8A3vNbAxQF1UdfjRxChsoNnOqArNHIhiGYJUkkeBsj9JidNj32nNnyCEqGVgMPVAvawZUNdsTezH94JW6KRpigq5kHe/LnpbBp006ro7t91JCy76/y+EJIkHC/0BsbeAKcbfhFt2fl9QKf1u1QnnjxjP5QPQXGfUHeGaZOLQeKkiOVr1Yvrpvww5QK+SxU7fcLxWdgeJz2HuXmWV+3PHjcH5U8i7BwYMCE92NAaieJoA06dJkmCurezAq8tnxfvY51gQv7+B13T+qqcN0Osx/dBHsIyIFEotZZ+sgxvjv+OGcbb5uGzknZkm7t9g8tX7LD3tg8Dvj57qFsU2uAeUK2yiONCOX62WCo7GgRBbQrK0BTh8JZ6Ow9sk/J59B90ENrLsz/bWs23o6iy5LaDGf2TQwNbCysUs7hAFnWmDJEem4TChgLN2wxUaHLNM9cNWhKpzcJItzh4iGgDuDk+lLIlQT/I7DoIqLoRprSadbT5jVPTYLGIcw/s3JDe528QcKu9zHxr42M/I8zaRJF4D5gtWXLU4kAEXu9Cjcl44tva8r34tnBjsmeQJ8jyYr+BWllh8krNKaM3PHPjPuZQ800sd1gk3ighbJmzO/6lUX0KjXV2SLUrt8mGzTgFOkUyj/iXtgy9sBS2NTu3rjXdBpeoTodxsGU= X-Forefront-Antispam-Report: CIP:165.204.84.17;CTRY:US;LANG:en;SCL:1;SRV:;IPV:CAL;SFV:NSPM;H:SATLEXMB04.amd.com;PTR:InfoDomainNonexistent;CAT:NONE;SFS:(13230022)(4636009)(376002)(396003)(346002)(39860400002)(136003)(451199015)(36840700001)(40470700004)(46966006)(6666004)(7696005)(40480700001)(316002)(478600001)(26005)(110136005)(54906003)(4326008)(8676002)(70586007)(70206006)(5660300002)(186003)(1076003)(8936002)(426003)(86362001)(336012)(44832011)(47076005)(66574015)(41300700001)(356005)(81166007)(2616005)(2906002)(36860700001)(83380400001)(36756003)(82740400003)(40460700003)(82310400005)(36900700001);DIR:OUT;SFP:1101; X-OriginatorOrg: amd.com X-MS-Exchange-CrossTenant-OriginalArrivalTime: 24 Nov 2022 17:02:47.5357 (UTC) X-MS-Exchange-CrossTenant-Network-Message-Id: 03cdf752-8518-41ee-539c-08dace3db68d X-MS-Exchange-CrossTenant-Id: 3dd8961f-e488-4e60-8e11-a82d994e183d X-MS-Exchange-CrossTenant-OriginalAttributedTenantConnectingIp: TenantId=3dd8961f-e488-4e60-8e11-a82d994e183d;Ip=[165.204.84.17];Helo=[SATLEXMB04.amd.com] X-MS-Exchange-CrossTenant-AuthSource: CO1NAM11FT059.eop-nam11.prod.protection.outlook.com X-MS-Exchange-CrossTenant-AuthAs: Anonymous X-MS-Exchange-CrossTenant-FromEntityHeader: HybridOnPrem X-MS-Exchange-Transport-CrossTenantHeadersStamped: BY5PR12MB4211 X-Spam-Status: No, score=-2.1 required=5.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID,DKIM_VALID_AU,DKIM_VALID_EF,RCVD_IN_DNSWL_NONE, RCVD_IN_MSPIKE_H2,SPF_HELO_PASS,SPF_PASS autolearn=ham autolearn_force=no version=3.4.6 X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on lindbergh.monkeyblade.net Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org X-getmail-retrieved-from-mailbox: =?utf-8?q?INBOX?= X-GMAIL-THRID: =?utf-8?q?1750397990079675838?= X-GMAIL-MSGID: =?utf-8?q?1750397990079675838?= The organization of the Spanish translations should be consistent with the rest of kernel documentation. Create directory process/ and move submitting-patches.rst there. Update indexes accordingly. Signed-off-by: Carlos Bilbao --- Documentation/translations/sp_SP/index.rst | 3 +-- Documentation/translations/sp_SP/process/index.rst | 13 +++++++++++++ .../sp_SP/{ => process}/submitting-patches.rst | 2 +- 3 files changed, 15 insertions(+), 3 deletions(-) create mode 100644 Documentation/translations/sp_SP/process/index.rst rename Documentation/translations/sp_SP/{ => process}/submitting-patches.rst (99%) diff --git a/Documentation/translations/sp_SP/index.rst b/Documentation/translations/sp_SP/index.rst index e20dd6e875e7..791cbef75902 100644 --- a/Documentation/translations/sp_SP/index.rst +++ b/Documentation/translations/sp_SP/index.rst @@ -1,4 +1,3 @@ -.. _sp_linux_doc: ===================== Traducción al español @@ -78,4 +77,4 @@ Traducciones al español :maxdepth: 1 howto - submitting-patches + process/index diff --git a/Documentation/translations/sp_SP/process/index.rst b/Documentation/translations/sp_SP/process/index.rst new file mode 100644 index 000000000000..ecdf6fa9df0c --- /dev/null +++ b/Documentation/translations/sp_SP/process/index.rst @@ -0,0 +1,13 @@ +.. raw:: latex + + \renewcommand\thesection* + \renewcommand\thesubsection* + +.. include:: ../disclaimer-sp.rst + +.. _sp_process_index: + +.. toctree:: + :maxdepth: 1 + + submitting-patches diff --git a/Documentation/translations/sp_SP/submitting-patches.rst b/Documentation/translations/sp_SP/process/submitting-patches.rst similarity index 99% rename from Documentation/translations/sp_SP/submitting-patches.rst rename to Documentation/translations/sp_SP/process/submitting-patches.rst index 5473bce87360..bf95ceb5e865 100644 --- a/Documentation/translations/sp_SP/submitting-patches.rst +++ b/Documentation/translations/sp_SP/process/submitting-patches.rst @@ -1,4 +1,4 @@ -.. include:: ./disclaimer-sp.rst +.. include:: ../disclaimer-sp.rst :Original: :ref:`Documentation/process/submitting-patches.rst ` :Translator: Carlos Bilbao From patchwork Thu Nov 24 17:02:41 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Carlos Bilbao X-Patchwork-Id: 25638 Return-Path: Delivered-To: ouuuleilei@gmail.com Received: by 2002:adf:f944:0:0:0:0:0 with SMTP id q4csp3511480wrr; Thu, 24 Nov 2022 09:05:17 -0800 (PST) X-Google-Smtp-Source: AA0mqf7z0lHEL1rnb9yvyHbHaGqbykNZ464bExBM30kiE5ooQMuuQmyTX7iLeIcrXEcb95Sod2ff X-Received: by 2002:a17:906:4546:b0:79b:f7d6:c2aa with SMTP id s6-20020a170906454600b0079bf7d6c2aamr12126990ejq.310.1669309517725; Thu, 24 Nov 2022 09:05:17 -0800 (PST) ARC-Seal: i=2; a=rsa-sha256; t=1669309517; cv=pass; d=google.com; s=arc-20160816; b=uapFn6dc5/Zeetsbul3VUJ98AyRnURkC6PKM2CpR7Y0XeSHECFcW/ZSz1R9cl8gblS bnRNM1I7XhKuBSE/FfL9nSTZaw2KCbcRWxGZRujkiMi2Q7kmdeNK0UcW8LQlEnRVcBvZ 8ob9ZsUSZJzodkGD6oULjdPps62jSzDq5i0OJ6THrHZXPDTpdqka/Z5w0MQ7cNCcFS4F DoQ4HAGjTGi/9Dnn0tiJYZPksrYWRBQLcgVh5iQkW7nhRfECVjGP5c6nCcBZYmX5n/e4 AI+qNY2QfyPVlttmtdG5r5+JvW7Lnw62O1zaA3CyFDGeR5agQrKuWWuB0LoUY/0pq3fW DZ9w== ARC-Message-Signature: i=2; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=list-id:precedence:content-transfer-encoding:mime-version :references:in-reply-to:message-id:date:subject:cc:to:from :dkim-signature; bh=Db1D8ug9/GltA0r3x1ETVzxepUSksvRIAhwEgIpeuNA=; b=uArvhf0+l8rVReujjmKx263uDerbA/9seWIJEtBuu+LL4w1hleNUEC14yeHrIXCV+0 nSPFoDlQ/SKG0+ghJ+lUuPOEZctkWYkkCzuC+fjmfkB/AOP0Ig4ifv20c3Ar6afS9Jnu SH+kD89LfYHmKMOoY/tgXqeKQ/1teJkV8f78GKGZcEaBEzwcML3BVXKUnnZMj5IyOSNg WOO2+NPwFiV++6mQdDXKucgxpmosd2So6pTCLxCufeAAXMNKIUUcPEy0HCqSGO2f2x+H /GXn1WR4FS/m6pvPoEkDzMqJ0y7xaz0vxrr7PZeTQxCGnOFyrrawToD9ZXWGIpYDhFcz oZLg== ARC-Authentication-Results: i=2; mx.google.com; dkim=pass header.i=@amd.com header.s=selector1 header.b=pGp67+7g; arc=pass (i=1 spf=pass spfdomain=amd.com dmarc=pass fromdomain=amd.com); spf=pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org; dmarc=pass (p=QUARANTINE sp=QUARANTINE dis=NONE) header.from=amd.com Received: from out1.vger.email (out1.vger.email. [2620:137:e000::1:20]) by mx.google.com with ESMTP id dz19-20020a0564021d5300b00468ccfbba7asi1483781edb.387.2022.11.24.09.04.52; Thu, 24 Nov 2022 09:05:17 -0800 (PST) Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) client-ip=2620:137:e000::1:20; Authentication-Results: mx.google.com; dkim=pass header.i=@amd.com header.s=selector1 header.b=pGp67+7g; arc=pass (i=1 spf=pass spfdomain=amd.com dmarc=pass fromdomain=amd.com); spf=pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org; dmarc=pass (p=QUARANTINE sp=QUARANTINE dis=NONE) header.from=amd.com Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S229695AbiKXRDK (ORCPT + 99 others); Thu, 24 Nov 2022 12:03:10 -0500 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:59154 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S229615AbiKXRCw (ORCPT ); Thu, 24 Nov 2022 12:02:52 -0500 Received: from NAM10-MW2-obe.outbound.protection.outlook.com (mail-mw2nam10on2064.outbound.protection.outlook.com [40.107.94.64]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 380BA2B1BB; Thu, 24 Nov 2022 09:02:50 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; s=arcselector9901; d=microsoft.com; cv=none; b=MzUIlsqQx1+uwW0O3dY8R2GF1TIlCYxhJjjVRuRaX+es/HZ8htfF1Ci0rgqpwU/A/SsNjocy09a/t+T+BmdWTyS8V8CC00FWD551BLM/1PplN43C4+OnFwlnqcf7xpwpOcZWjEWAKIvfn27OaI8pmVB8dF4h0+2r3bZiBDUPEFt6fFPfgiA6qek+PByFXfqsSbJFdyLqvnxZW/0EWww8GhdPluEX7A1YWo8n/jcmgx67QuV8d9WYuRSvjf6GowtHBL2la0g1NCLxa9V7fUuutfNBwfZsF+4U/mqaiCNMKsDca2HQo006fsexJ4C6HvQ8vbVgpTP4LSjPBbSBM1EEOw== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=microsoft.com; s=arcselector9901; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-AntiSpam-MessageData-ChunkCount:X-MS-Exchange-AntiSpam-MessageData-0:X-MS-Exchange-AntiSpam-MessageData-1; bh=Db1D8ug9/GltA0r3x1ETVzxepUSksvRIAhwEgIpeuNA=; b=IEvtsTorziTE+cKsMIDVCWvceoIk3bqD4hD1ByC8gAT73rp3e0Y0whNzkTLKqLLd8d9rat1XpmLeAI+LpWKizXxTsdYz53vkQwT5I443LwPH4CC9/MlO/h1XtohhQwC+HxToIiB4qlAVNGnAwgRy6GBILNBH8eQGSOGy93FrQeS3Ss6hyx9yBRlAPuEAYYcdmUQZXDEdXMk0mUDKVSUIQiTXqtJRZR83S80VIUkomAGiyeuKj30AUoWGBRWBM0ZvSTxnpRmg06G6m9BnnF6GfvLMa094ATpU7WjNf9X7TICoKM3HKigftPUAPgHRpf+QkOVfrEVJ1qQWsoHFxiLL7A== ARC-Authentication-Results: i=1; mx.microsoft.com 1; spf=pass (sender ip is 165.204.84.17) smtp.rcpttodomain=lwn.net smtp.mailfrom=amd.com; dmarc=pass (p=quarantine sp=quarantine pct=100) action=none header.from=amd.com; dkim=none (message not signed); arc=none DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=amd.com; s=selector1; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-SenderADCheck; bh=Db1D8ug9/GltA0r3x1ETVzxepUSksvRIAhwEgIpeuNA=; b=pGp67+7gRR+szupHZaPM76MP4Vpv79/XRByU/Nxb/5H5Js8E729cs5cojy+nrCz6QD9iuNl6lZ52o+jkA5vlR/4cw4q3wtCfw61ooJokpMm5zb06ad+uw8KjLrZZHjGOUxxCo1uF7qxqDLu03thAEt9dLEzGC3jG9K2s8gaVfzg= Received: from DM5PR07CA0053.namprd07.prod.outlook.com (2603:10b6:4:ad::18) by PH8PR12MB7350.namprd12.prod.outlook.com (2603:10b6:510:216::12) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.5857.19; Thu, 24 Nov 2022 17:02:48 +0000 Received: from DM6NAM11FT004.eop-nam11.prod.protection.outlook.com (2603:10b6:4:ad:cafe::bd) by DM5PR07CA0053.outlook.office365.com (2603:10b6:4:ad::18) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.5857.19 via Frontend Transport; Thu, 24 Nov 2022 17:02:47 +0000 X-MS-Exchange-Authentication-Results: spf=pass (sender IP is 165.204.84.17) smtp.mailfrom=amd.com; dkim=none (message not signed) header.d=none;dmarc=pass action=none header.from=amd.com; Received-SPF: Pass (protection.outlook.com: domain of amd.com designates 165.204.84.17 as permitted sender) receiver=protection.outlook.com; client-ip=165.204.84.17; helo=SATLEXMB03.amd.com; pr=C Received: from SATLEXMB03.amd.com (165.204.84.17) by DM6NAM11FT004.mail.protection.outlook.com (10.13.172.217) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256) id 15.20.5834.8 via Frontend Transport; Thu, 24 Nov 2022 17:02:47 +0000 Received: from SATLEXMB06.amd.com (10.181.40.147) by SATLEXMB03.amd.com (10.181.40.144) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256) id 15.1.2375.34; Thu, 24 Nov 2022 11:02:46 -0600 Received: from SATLEXMB04.amd.com (10.181.40.145) by SATLEXMB06.amd.com (10.181.40.147) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256) id 15.1.2375.34; Thu, 24 Nov 2022 11:02:46 -0600 Received: from iron-maiden.amd.com (10.180.168.240) by SATLEXMB04.amd.com (10.181.40.145) with Microsoft SMTP Server id 15.1.2375.34 via Frontend Transport; Thu, 24 Nov 2022 11:02:46 -0600 From: Carlos Bilbao To: , , CC: , , , Carlos Bilbao Subject: [PATCH 5/6] docs/sp_SP: Add kernel-docs.rst Spanish translation Date: Thu, 24 Nov 2022 11:02:41 -0600 Message-ID: <20221124170242.1892751-6-carlos.bilbao@amd.com> X-Mailer: git-send-email 2.34.1 In-Reply-To: <20221124170242.1892751-1-carlos.bilbao@amd.com> References: <20221124170242.1892751-1-carlos.bilbao@amd.com> MIME-Version: 1.0 X-EOPAttributedMessage: 0 X-MS-PublicTrafficType: Email X-MS-TrafficTypeDiagnostic: DM6NAM11FT004:EE_|PH8PR12MB7350:EE_ X-MS-Office365-Filtering-Correlation-Id: 9595d832-7aca-496b-62ca-08dace3db670 X-MS-Exchange-SenderADCheck: 1 X-MS-Exchange-AntiSpam-Relay: 0 X-Microsoft-Antispam: BCL:0; X-Microsoft-Antispam-Message-Info: iXHZgkFT72aIPY/ug3/Rg39nS0aO6FmXNjuFHYFhrlYNDtbOMhKSeBmcu8Zh7oWfAcDRldhINbb+e4FE/sYZWb/+kLqkjMZvVoncUODFhF9ZM/0oMSXkYoWLc8axbcg8D7q4kHzeB6W0p5vvZIbLreozMPD5YCT/VCmdlRvucMYiMaSw8sasw4J45c9XMifooBQakRa/7vUr+1YR4l/fsjkmY8wXKwVoclj1zILY8WdQ0pSXd1cI9IoS51nIV+mjNNzwZ386/RBZV6n0mPBZwOv+QQ85wjsYO/YB0P12bhbEjbHRwijb4MB3UgTZ+yvoF0XFljXltIm5+kT+L8vftMJLz5lsld6ld+nU8k7KBQKuB48tAeyHgioKiNd9BaNLDUmtYaTek0/G2g+ICMuNqW44zcFrE2EdjoSgfCjbSPvv3n8omJ92bF4a/jvno5001IlCRelwPl09PWHrazPgiQ4LEEwBzpQhEDExTCiPk5Zm+zxGiud89CDL1QbTjKQ3ULtNvEH42W+1zsl0h9p+nWAOL21CCB9VmlIZ4p9+4NLbZervq5he22mbCzxeWjlLuS9LNU4KLN2r1arDr61pryZO8koo29gd9HqMBuIzb9T3SoEdQYcJholB5E7qHyZLVxLDQjybpjGedc4PzSmS+imeuaAcWeDTd0e+L6Vbd/NLAiJrjrLwUF4D59gJF5hQD7X97fre+Mnk2atu09GlPBBxzUQBS/9JNGk65AIt+/AEauOeF7LeJfMkBvvDY/5i+LRBcyFRGK/ck4UM51Ga8yAHKk/zk/uHk65FHHeqrSdrG5tB/EcEb4hNCpaEbhiDzrmSyeJ7tw+rif90SjJVqw== X-Forefront-Antispam-Report: CIP:165.204.84.17;CTRY:US;LANG:es;SCL:1;SRV:;IPV:CAL;SFV:NSPM;H:SATLEXMB03.amd.com;PTR:InfoDomainNonexistent;CAT:NONE;SFS:(13230022)(4636009)(39860400002)(346002)(136003)(396003)(376002)(451199015)(36840700001)(46966006)(40470700004)(36756003)(86362001)(40480700001)(8676002)(70586007)(4326008)(70206006)(82740400003)(81166007)(356005)(36860700001)(82310400005)(478600001)(83380400001)(6666004)(7696005)(1076003)(2616005)(26005)(2906002)(47076005)(41300700001)(426003)(54906003)(110136005)(44832011)(5660300002)(316002)(336012)(186003)(8936002)(40460700003)(966005)(36900700001)(562404015);DIR:OUT;SFP:1101; X-OriginatorOrg: amd.com X-MS-Exchange-CrossTenant-OriginalArrivalTime: 24 Nov 2022 17:02:47.4554 (UTC) X-MS-Exchange-CrossTenant-Network-Message-Id: 9595d832-7aca-496b-62ca-08dace3db670 X-MS-Exchange-CrossTenant-Id: 3dd8961f-e488-4e60-8e11-a82d994e183d X-MS-Exchange-CrossTenant-OriginalAttributedTenantConnectingIp: TenantId=3dd8961f-e488-4e60-8e11-a82d994e183d;Ip=[165.204.84.17];Helo=[SATLEXMB03.amd.com] X-MS-Exchange-CrossTenant-AuthSource: DM6NAM11FT004.eop-nam11.prod.protection.outlook.com X-MS-Exchange-CrossTenant-AuthAs: Anonymous X-MS-Exchange-CrossTenant-FromEntityHeader: HybridOnPrem X-MS-Exchange-Transport-CrossTenantHeadersStamped: PH8PR12MB7350 X-Spam-Status: No, score=-2.1 required=5.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID,DKIM_VALID_AU,DKIM_VALID_EF,RCVD_IN_DNSWL_NONE, RCVD_IN_MSPIKE_H2,SPF_HELO_PASS,SPF_PASS autolearn=ham autolearn_force=no version=3.4.6 X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on lindbergh.monkeyblade.net Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org X-getmail-retrieved-from-mailbox: =?utf-8?q?INBOX?= X-GMAIL-THRID: =?utf-8?q?1750397896567952144?= X-GMAIL-MSGID: =?utf-8?q?1750397896567952144?= Translate Documentation/process/kernel-docs.rst into Spanish. Signed-off-by: Carlos Bilbao --- .../translations/sp_SP/process/index.rst | 1 + .../sp_SP/process/kernel-docs.rst | 187 ++++++++++++++++++ 2 files changed, 188 insertions(+) create mode 100644 Documentation/translations/sp_SP/process/kernel-docs.rst diff --git a/Documentation/translations/sp_SP/process/index.rst b/Documentation/translations/sp_SP/process/index.rst index ecdf6fa9df0c..4acb7f5005af 100644 --- a/Documentation/translations/sp_SP/process/index.rst +++ b/Documentation/translations/sp_SP/process/index.rst @@ -11,3 +11,4 @@ :maxdepth: 1 submitting-patches + kernel-docs diff --git a/Documentation/translations/sp_SP/process/kernel-docs.rst b/Documentation/translations/sp_SP/process/kernel-docs.rst new file mode 100644 index 000000000000..62b8105445fb --- /dev/null +++ b/Documentation/translations/sp_SP/process/kernel-docs.rst @@ -0,0 +1,187 @@ +.. include:: ../disclaimer-sp.rst + +:Original: :ref:`Documentation/process/kernel-docs.rst ` +:Translator: Carlos Bilbao + +.. _sp_kernel_docs: + +Índice de documentación adicional del kernel +============================================ + +La necesidad de un documento como este se hizo evidente en la lista de +correo de linux-kernel cuando las mismas preguntas, solicitando sugerencias +e información, aparecieron una y otra vez. + +Afortunadamente, a medida que más y más gente accede a GNU/Linux, más +desarrolladores se interesan por el kernel. Sin embargo, leer las fuentes +no siempre es suficiente. Es fácil entender el código, pero se pierden los +conceptos, la filosofía y decisiones de diseño detrás de dicho código. + +Desafortunadamente, no existen muchos documentos disponibles para que los +principiantes comiencen. Y, aunque existieran, no habría ningún lugar +"conocido" que les pudiera seguir la pista. Estas líneas tratan de cubrir +esta carencia. + +POR FAVOR, si conoce algún documento que no figura aquí, o si escribe un +nuevo documento, incluya una referencia aquí, siguiendo el proceso de envío +de parches del kernel. Cualquier corrección, idea o comentario también es +bienvenida. + +Todos los documentos se catalogan con los siguientes campos: el "Título", +el "Autor"/es, la "URL" donde se encuentran, algunas "Palabras clave" +útiles para buscar temas específicos, y una breve "Descripción" del +documento en cuestión. + +.. note:: + + Los documentos de cada sección en este documento están ordenados por su + fecha de publicación, del más reciente al más antiguo. Los maintainers + deben ir retirando recursos obsoletos o anticuados. + +Documentos en el árbol del kernel Linux +----------------------------------------- + +Los libros de Sphinx deben compilarse con ``make {htmldocs | pdfdocs | epubdocs}``. + + * Título: **linux/Documentation** + + :Autor: Many. + :Ubicación: Documentation/ + :Palabras Clave: archivos de texto, Sphinx. + :Descripción: Documentación que viene con las fuentes del kernel, + dentro del directorio Documentation. Algunas páginas de este documento + (incluido este documento en sí) se han trasladado allí, y podrían + estar más actualizadas que la versión web. + +Documentos en línea +------------------- + + * Título: **Linux Kernel Mailing List Glossary** + + :Autor: various + :URL: https://kernelnewbies.org/KernelGlossary + :Fecha: rolling version + :Palabras Clave: glosario terminos, linux-kernel. + :Descripción: De la Introducción: "This glossary is intended as + a brief description of some of the acronyms and terms you may hear + during discussion of the Linux kernel". + + * Título: **The Linux Kernel Module Programming Guide** + + :Autor: Peter Jay Salzman, Michael Burian, Ori Pomerantz, Bob Mottram, + Jim Huang. + :URL: https://sysprog21.github.io/lkmpg/ + :Fecha: 2021 + :Palabras Clave: modules, GPL book, /proc, ioctls, system calls, + interrupt handlers, llamadas al sistema, interrupciones. + :Descripción: Un muy buen libro GPL sobre el tema de la programación + de módulos. Muchos ejemplos. Actualmente la nueva versión está + siendo mantenida activamente ent https://github.com/sysprog21/lkmpg. + +Libros publicados +----------------- + + * Título: **Linux Kernel Programming: A Comprehensive Guide to Kernel Internals, Writing Kernel Modules, and Kernel Synchronization** + + :Autor: Kaiwan N. Billimoria + :Publica: Packt Publishing Ltd + :Fecha: 2021 + :Paginas: 754 + :ISBN: 978-1789953435 + + * Título: **Linux Kernel Development, 3rd Edition** + + :Autor: Robert Love + :Publica: Addison-Wesley + :Fecha: July, 2010 + :Paginas: 440 + :ISBN: 978-0672329463 + :Notas: Libro fundacional + +.. _sp_ldd3_published: + + * Título: **Linux Device Drivers, 3rd Edition** + + :Authors: Jonathan Corbet, Alessandro Rubini, and Greg Kroah-Hartman + :Publica: O'Reilly & Associates + :Fecha: 2005 + :Paginas: 636 + :ISBN: 0-596-00590-3 + :Notas: Libro fundacional. Más información en + http://www.oreilly.com/catalog/linuxdrive3/ + formato PDF, URL: https://lwn.net/Kernel/LDD3/ + + * Título: **The Design of the UNIX Operating System** + + :Autor: Maurice J. Bach + :Publica: Prentice Hall + :Fecha: 1986 + :Paginas: 471 + :ISBN: 0-13-201757-1 + :Notas: Libro fundacional + +Recursos varios +--------------- + + * Título: **Cross-Referencing Linux** + + :URL: https://elixir.bootlin.com/ + :Palabras Clave: Browsing source code. + :Descripción: Otro navegador de código fuente del kernel Linux que se + encuentra en la web. Muchas referencias cruzadas a variables y + funciones. Puedes ver dónde se definen y dónde se utilizan. + + * Título: **Linux Weekly News** + + :URL: https://lwn.net + :Palabras Clave: latest kernel news, noticias del kernel Linux. + :Descripción: El título lo dice todo (Noticias Semanales de Linux). + Hay una sección fija sobre el kernel, resumiendo el trabajo de sus + desarrolladores, correcciones de errores, nuevas funciones y + versiones, producido durante la semana. + + * Título: **The home page of Linux-MM** + + :Autor: The Linux-MM team. + :URL: https://linux-mm.org/ + :Palabras Clave: memory management, Linux-MM, mm patches, TODO, docs, + mailing list, administración de memoria, Linux-MM, parches mm, listas + de correo. + :Descripción: Sitio dedicado al desarrollo de la gestión de memoria + de Linux. Parches relacionados con la memoria, HOWTOs, enlaces, + desarrolladores de mm... ¡Si está interesado en el desarrollo de la + gestión de memoria no te lo pierdas! + + * Título: **Kernel Newbies IRC Channel and Website** + + :URL: https://www.kernelnewbies.org + :Palabras Clave: IRC, newbies, channel, asking doubts, canal, dudas, + novatos, preguntar. + :Descripción: #kernelnewbies en irc.oftc.net. + #kernelnewbies es una red de IRC dedicada al hacker del kernel + 'novato'. La audiencia se compone principalmente de personas que + quieren aprender sobre el kernel, trabajar en proyectos del kernel + o hackers profesionales del kernel que quieren ayudar a la gente + menos experimentada. + #kernelnewbies es parte de la red OFTC IRC. + Pruebe con irc.oftc.net como su servidor y luego haga /join + #kernelnewbies. + El sitio web kernelnewbies también alberga artículos, documentos, FAQs... + + * Título: **linux-kernel mailing list archives and search engines** + + :URL: http://vger.kernel.org/vger-lists.html + :URL: http://www.uwsg.indiana.edu/hypermail/linux/kernel/index.html + :URL: http://groups.google.com/group/mlist.linux.kernel + :Palabras Clave: linux-kernel, archives, buscar, search, archivos. + :Descripción: Algunos de los archivadores de listas de correo del + kernel de Linux. Si usted tiene uno mejor/otro, por favor hágamelo + saber. + +------- + +Este documento se basaba originalmente en: + + https://www.dit.upm.es/~jmseyas/linux/kernel/hackers-docs.html + +escrito por Juan-Mariano de Goyenche From patchwork Thu Nov 24 17:02:42 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Carlos Bilbao X-Patchwork-Id: 25640 Return-Path: Delivered-To: ouuuleilei@gmail.com Received: by 2002:adf:f944:0:0:0:0:0 with SMTP id q4csp3511846wrr; Thu, 24 Nov 2022 09:05:49 -0800 (PST) X-Google-Smtp-Source: AA0mqf64NfJQDcKtQ0RNSRjKgCoGMxp3cFrvKmCv3tt5sPUnqF2B++aJgCuzqxbn4vTAn81m5zQT X-Received: by 2002:aa7:d74c:0:b0:461:b952:8932 with SMTP id a12-20020aa7d74c000000b00461b9528932mr22719715eds.104.1669309549707; Thu, 24 Nov 2022 09:05:49 -0800 (PST) ARC-Seal: i=2; a=rsa-sha256; t=1669309549; cv=pass; d=google.com; s=arc-20160816; b=mYX1UONfMDGqItcKHihwTami9O13VH3kHWhwvBpUtR7loySKHoquvq8n0DKy24TQrD ETWvZYFoWRbo5MtPN9fQj9kgFluoE2z42rIa5O90nPEGkI7dyNOeyygjLxds/zy0OPeA Zi/CQodvHEv1Dx3d1g35h30vy/DfV+oH/UCjR4DCPfN31SN2VBTdle/gpYy6aw3zyILP p4sE5ee8s8h+il7/QOxwDfOdh8fHK9TNuuJASR0b7PWtUaUf1J0IpnvbcB19FVvLDh6y LBFtVPxrO4LDNEvamPflKiDyX7XzqLOMqnU/YstmeA9DudlI5k2dSlRR3rEilmNRfukK xu5w== ARC-Message-Signature: i=2; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=list-id:precedence:content-transfer-encoding:mime-version :references:in-reply-to:message-id:date:subject:cc:to:from :dkim-signature; bh=YAUfC45BKnf0z7do1T0BoRp4YJGArk6DJNFj+9F1qJk=; b=f+4n2q1Xg/ZrBsCxEFIcceux/lIdEA7/4CwEGUjQiW8r0m9KN3blTGZhhMvVLyhJto k+D68RCURd2hXlo7/F1BL6i/kmTfvfRXvqoD9BdQeiDMZlzqsiAYTLId6wlNrg+e0/8j DSiY1TMKNBBtBdfLDbpTHSKJTd0P9OW2zTyECWxTZsAvsL6MmoaDFtZAc7SRYvbuHf0E kLQE515aCIgdJCuzi0lGliVKRSECBSoOp5JRzuucAolRJ8O0K5d0xGG80xVw4HRTPZnS ScuRPBWFZUSTLoVn3lGh6S4Lbvf2drj4CFDq0hN34M9R3j/wFI0uY5IA3LiyFawc+jg3 2jkA== ARC-Authentication-Results: i=2; mx.google.com; dkim=pass header.i=@amd.com header.s=selector1 header.b=xqazRO4p; arc=pass (i=1 spf=pass spfdomain=amd.com dmarc=pass fromdomain=amd.com); spf=pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org; dmarc=pass (p=QUARANTINE sp=QUARANTINE dis=NONE) header.from=amd.com Received: from out1.vger.email (out1.vger.email. [2620:137:e000::1:20]) by mx.google.com with ESMTP id gn13-20020a1709070d0d00b007824786a7easi1421183ejc.724.2022.11.24.09.05.24; Thu, 24 Nov 2022 09:05:49 -0800 (PST) Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) client-ip=2620:137:e000::1:20; Authentication-Results: mx.google.com; dkim=pass header.i=@amd.com header.s=selector1 header.b=xqazRO4p; arc=pass (i=1 spf=pass spfdomain=amd.com dmarc=pass fromdomain=amd.com); spf=pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org; dmarc=pass (p=QUARANTINE sp=QUARANTINE dis=NONE) header.from=amd.com Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S229733AbiKXRDO (ORCPT + 99 others); Thu, 24 Nov 2022 12:03:14 -0500 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:59366 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S229693AbiKXRC4 (ORCPT ); Thu, 24 Nov 2022 12:02:56 -0500 Received: from NAM12-BN8-obe.outbound.protection.outlook.com (mail-bn8nam12on2070.outbound.protection.outlook.com [40.107.237.70]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id D47EE28E30; Thu, 24 Nov 2022 09:02:51 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; s=arcselector9901; d=microsoft.com; cv=none; b=TTcDhea9GaRtShaZFm3HBy9uiJ4U5H3N2mCLUW5IJ4zdURRTXz7XEZgNWsl/Qo2Alff0TIG9RAqmsIDeVfR6ekOf9qh93kXK1DKNkjgTbuGKxGuD9JP26zq+Wl1eCjnShywAqOMmqHeCoas9LSrJTU5u+qqfrLhgp1xkIlnK9Z+SPYc1J+22OfaVOydULu1Vr1xf3w0dbtcSksFr+YaIxx3vgNZ3eeH78EV1QRtDQfa4wXXt8VJq+Bk4ft/Dbr4oIUBo8JmozVftyp31mvRNHD72Pv+5D0WjqoRUzkBQIgt/EKM03W4fzRP+nwdA8iJvggtmSgqx/p1q1uv0WEHiwg== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=microsoft.com; s=arcselector9901; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-AntiSpam-MessageData-ChunkCount:X-MS-Exchange-AntiSpam-MessageData-0:X-MS-Exchange-AntiSpam-MessageData-1; bh=YAUfC45BKnf0z7do1T0BoRp4YJGArk6DJNFj+9F1qJk=; b=Gheo/PK/2Z1bp4wqcEWZVTdYcnshiYYlT0JBgXOhJ+5qG+85uU6X2ldi+0gJE2by7m15VtlRG8ky2oGJ/Kx/rs0jWA7NV2am399p2WVQfZ76IZ3mxu4LTy/i9hwK0x2xr/bqKEHoc8j85zHnOVUkQuMKxd4zVeK1e0/SgYIPyDzoGymHAqdVbQ6pLh35G92WPFYVSMVt90fFVnQJnS4GtYX1jqW+wL+ihI848WQzbJdQzAFrifksvsQwIk+kVeNICitsq9eNYe6y9/tbPH5u7KUBWixlIZKY3a7mxxezJlhHMzYQzOrM62cjKd59naQLWZJ4MA+n8OdUrRLtTjmgQA== ARC-Authentication-Results: i=1; mx.microsoft.com 1; spf=pass (sender ip is 165.204.84.17) smtp.rcpttodomain=lwn.net smtp.mailfrom=amd.com; dmarc=pass (p=quarantine sp=quarantine pct=100) action=none header.from=amd.com; dkim=none (message not signed); arc=none DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=amd.com; s=selector1; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-SenderADCheck; bh=YAUfC45BKnf0z7do1T0BoRp4YJGArk6DJNFj+9F1qJk=; b=xqazRO4pEOQl7T2qzFTznbLvpCHp7jhnzcXNCh4HYf6W+BYOoS/mF1U4my9YMX1OIzLD9wu+qzlb/xo8eMxyNNYgFgcjXDdwDg2ZbouLoeP3oPaE5duN0ukWcPliycf+pw5tilYNjLmAJcVx9eCv/qgotFyp8tAvWz0k3XnX5Rc= Received: from DM5PR07CA0081.namprd07.prod.outlook.com (2603:10b6:4:ad::46) by DM6PR12MB4532.namprd12.prod.outlook.com (2603:10b6:5:2af::24) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.5857.19; Thu, 24 Nov 2022 17:02:48 +0000 Received: from DM6NAM11FT004.eop-nam11.prod.protection.outlook.com (2603:10b6:4:ad:cafe::12) by DM5PR07CA0081.outlook.office365.com (2603:10b6:4:ad::46) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.5857.19 via Frontend Transport; Thu, 24 Nov 2022 17:02:48 +0000 X-MS-Exchange-Authentication-Results: spf=pass (sender IP is 165.204.84.17) smtp.mailfrom=amd.com; dkim=none (message not signed) header.d=none;dmarc=pass action=none header.from=amd.com; Received-SPF: Pass (protection.outlook.com: domain of amd.com designates 165.204.84.17 as permitted sender) receiver=protection.outlook.com; client-ip=165.204.84.17; helo=SATLEXMB03.amd.com; pr=C Received: from SATLEXMB03.amd.com (165.204.84.17) by DM6NAM11FT004.mail.protection.outlook.com (10.13.172.217) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256) id 15.20.5834.8 via Frontend Transport; Thu, 24 Nov 2022 17:02:48 +0000 Received: from SATLEXMB05.amd.com (10.181.40.146) by SATLEXMB03.amd.com (10.181.40.144) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256) id 15.1.2375.34; Thu, 24 Nov 2022 11:02:47 -0600 Received: from SATLEXMB04.amd.com (10.181.40.145) by SATLEXMB05.amd.com (10.181.40.146) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256) id 15.1.2375.34; Thu, 24 Nov 2022 11:02:47 -0600 Received: from iron-maiden.amd.com (10.180.168.240) by SATLEXMB04.amd.com (10.181.40.145) with Microsoft SMTP Server id 15.1.2375.34 via Frontend Transport; Thu, 24 Nov 2022 11:02:46 -0600 From: Carlos Bilbao To: , , CC: , , , Carlos Bilbao Subject: [PATCH 6/6] docs/sp_SP: Add process coding-style translation Date: Thu, 24 Nov 2022 11:02:42 -0600 Message-ID: <20221124170242.1892751-7-carlos.bilbao@amd.com> X-Mailer: git-send-email 2.34.1 In-Reply-To: <20221124170242.1892751-1-carlos.bilbao@amd.com> References: <20221124170242.1892751-1-carlos.bilbao@amd.com> MIME-Version: 1.0 X-EOPAttributedMessage: 0 X-MS-PublicTrafficType: Email X-MS-TrafficTypeDiagnostic: DM6NAM11FT004:EE_|DM6PR12MB4532:EE_ X-MS-Office365-Filtering-Correlation-Id: 5d811f2e-d1e1-4677-46c5-08dace3db6f8 X-MS-Exchange-SenderADCheck: 1 X-MS-Exchange-AntiSpam-Relay: 0 X-Microsoft-Antispam: BCL:0; X-Microsoft-Antispam-Message-Info: rgGqKgAPO7UVco3qWu3/TuP5+phTn3SN7gIZmBO+oG4XD5uizq1ntB/Jj5keuiaZAp6dwAmGwSDxZashTqbQ3OKq7UTaqDnI9BpuUOOdk7iXPOOvBeFFW8GX5EE4m6kDYyZZFKFGgjGU1eIhgmuGwCE0eDrOjowEO49m06/1GZjHeyBnJ+HTSrxCzDZ4JC15Z9opfFlO8RzvghpmAKZM66aXw+f8gXCWXmoAxmYDxSDVRgNw/zgttzwMYVHKgWd4Uhv5PhZ4IdkHa6RtJOzeSVQWRyeRxGhnubSKEZ4RinXpb+XgPy8l42+VbgU6BajbllIUW80bPFZ5YeS3s2MYswrQneyVhGalXDz2RytPGt4FBV9BFcWxPtVerv5ELGPanPviMy148xWvAtEDwOuDhRALBtaAohjEqT7VmqNskuf51ymlynshJ7qkrXO8beLNN7yezfDXOanF1vJzjKwsTCcQkm40dLIJq+sQh6yV4fs9hmI37CoYmDktf4OrbM10U2mKE7WAgnotkprqHVB6ti2z5KXYkJ5JpCzVr2h4+XZk6Hxa2XiSWUHOQl/UX9UOgLWK1R6lPfwR3nrVWJ+8XXD4tQbaCMTaXt2fvvBDVNBBIuhQPfnB5ZIq5AdGcl5XIwwXKNB3Qi7dtDlcdVFTUz+w9OuxDiVeCIM3D+66PGbjSo+fTZ4j27IBIxhf0ctkzD/4esiQcmzq7RODiSeXju7HDAhbrsqqXvuz/JmQ3xM/+FHqRMywx4dztgmu5Und6MucalO+bjwV79CNf5CQFocyRusq7cNouBIzkzGJqro7BBXU90JSMVf5FZ1lKYlm X-Forefront-Antispam-Report: CIP:165.204.84.17;CTRY:US;LANG:es;SCL:1;SRV:;IPV:CAL;SFV:NSPM;H:SATLEXMB03.amd.com;PTR:InfoDomainNonexistent;CAT:NONE;SFS:(13230022)(4636009)(346002)(136003)(376002)(39860400002)(396003)(451199015)(36840700001)(40470700004)(46966006)(2906002)(82740400003)(356005)(40480700001)(83380400001)(81166007)(8936002)(26005)(36756003)(41300700001)(316002)(54906003)(110136005)(86362001)(2616005)(336012)(186003)(66574015)(426003)(1076003)(47076005)(5660300002)(82310400005)(6666004)(30864003)(44832011)(7696005)(70586007)(36860700001)(70206006)(478600001)(66899015)(8676002)(966005)(4326008)(40460700003)(21314003)(36900700001)(559001)(579004);DIR:OUT;SFP:1101; X-OriginatorOrg: amd.com X-MS-Exchange-CrossTenant-OriginalArrivalTime: 24 Nov 2022 17:02:48.3616 (UTC) X-MS-Exchange-CrossTenant-Network-Message-Id: 5d811f2e-d1e1-4677-46c5-08dace3db6f8 X-MS-Exchange-CrossTenant-Id: 3dd8961f-e488-4e60-8e11-a82d994e183d X-MS-Exchange-CrossTenant-OriginalAttributedTenantConnectingIp: TenantId=3dd8961f-e488-4e60-8e11-a82d994e183d;Ip=[165.204.84.17];Helo=[SATLEXMB03.amd.com] X-MS-Exchange-CrossTenant-AuthSource: DM6NAM11FT004.eop-nam11.prod.protection.outlook.com X-MS-Exchange-CrossTenant-AuthAs: Anonymous X-MS-Exchange-CrossTenant-FromEntityHeader: HybridOnPrem X-MS-Exchange-Transport-CrossTenantHeadersStamped: DM6PR12MB4532 X-Spam-Status: No, score=-2.1 required=5.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID,DKIM_VALID_AU,DKIM_VALID_EF,RCVD_IN_DNSWL_NONE, RCVD_IN_MSPIKE_H2,SPF_HELO_PASS,SPF_PASS autolearn=ham autolearn_force=no version=3.4.6 X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on lindbergh.monkeyblade.net Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org X-getmail-retrieved-from-mailbox: =?utf-8?q?INBOX?= X-GMAIL-THRID: =?utf-8?q?1750397930559155752?= X-GMAIL-MSGID: =?utf-8?q?1750397930559155752?= Translate Documentation/process/coding-style.rst into Spanish. Signed-off-by: Carlos Bilbao --- .../sp_SP/process/coding-style.rst | 1315 +++++++++++++++++ .../translations/sp_SP/process/index.rst | 1 + 2 files changed, 1316 insertions(+) create mode 100644 Documentation/translations/sp_SP/process/coding-style.rst diff --git a/Documentation/translations/sp_SP/process/coding-style.rst b/Documentation/translations/sp_SP/process/coding-style.rst new file mode 100644 index 000000000000..a0261ba5b902 --- /dev/null +++ b/Documentation/translations/sp_SP/process/coding-style.rst @@ -0,0 +1,1315 @@ +.. include:: ../disclaimer-sp.rst + +:Original: :ref:`Documentation/process/coding-style.rst ` +:Translator: Carlos Bilbao + +.. _sp_codingstyle: + +Estilo en el código del kernel Linux +===================================== + +Este es un breve documento que describe el estilo preferido en el código +del kernel Linux. El estilo de código es muy personal y no **forzaré** mi +puntos de vista sobre nadie, pero esto vale para todo lo que tengo que +mantener, y preferiría que para la mayoría de otras cosas también. Por +favor, por lo menos considere los argumentos expuestos aquí. + +En primer lugar, sugeriría imprimir una copia de los estándares de código +GNU, y NO leerlo. Quémelos, es un gran gesto simbólico. + +De todos modos, aquí va: + + +1) Sangría +----------- + +Las tabulaciones tienen 8 caracteres y, por lo tanto, las sangrías también +tienen 8 caracteres. Hay movimientos heréticos que intentan hacer sangría +de 4 (¡o incluso 2!) caracteres de longitud, y eso es similar a tratar de +definir el valor de PI como 3. + +Justificación: La idea detrás de la sangría es definir claramente dónde +comienza y termina un bloque de control. Especialmente, cuando ha estado +buscando en su pantalla durante 20 horas seguidas, le resultará mucho más +fácil ver cómo funciona la sangría si tiene sangrías grandes. + +Bueno, algunas personas dirán que tener sangrías de 8 caracteres hace que +el código se mueva demasiado a la derecha y dificulta la lectura en una +pantalla de terminal de 80 caracteres. La respuesta a eso es que si +necesita más de 3 niveles de sangría, está en apuros de todos modos y +debería arreglar su programa. + +En resumen, las sangrías de 8 caracteres facilitan la lectura y tienen la +ventaja añadida de advertirle cuando está anidando sus funciones demasiado +profundo. Preste atención a esa advertencia. + +La forma preferida de facilitar múltiples niveles de sangría en una +declaración de switch es para alinear el ``switch`` y sus etiquetas +``case`` subordinadas en la misma columna, en lugar de hacer ``doble +sangría`` (``double-indenting``) en etiquetas ``case``. Por ejemplo: + +.. code-block:: c + + switch (suffix) { + case 'G': + case 'g': + mem <<= 30; + break; + case 'M': + case 'm': + mem <<= 20; + break; + case 'K': + case 'k': + mem <<= 10; + fallthrough; + default: + break; + } + +No ponga varias declaraciones en una sola línea a menos que tenga algo que +ocultar: + +.. code-block:: c + + if (condición) haz_esto; + haz_otra_cosa; + +No use comas para evitar el uso de llaves: + +.. code-block:: c + + if (condición) + haz_esto(), haz_eso(); + +Siempre use llaves para múltiples declaraciones: + +.. code-block:: c + + if (condición) { + haz_esto(); + haz_eso(); + } + +Tampoco ponga varias asignaciones en una sola línea. El estilo de código +del kernel es súper simple. Evite las expresiones engañosas. + + +Aparte de los comentarios, la documentación y excepto en Kconfig, los +espacios nunca se utilizan para la sangría, y el ejemplo anterior se rompe +deliberadamente. + +Consiga un editor decente y no deje espacios en blanco al final de las +líneas. + +2) Rompiendo líneas y strings largos +------------------------------------ + +El estilo de código tiene todo que ver con la legibilidad y la +mantenibilidad usando herramientas disponibles comúnmente. + +El límite preferido en la longitud de una sola línea es de 80 columnas. + +Las declaraciones de más de 80 columnas deben dividirse en partes, a menos +que exceder las 80 columnas aumente significativamente la legibilidad y no +oculte información. + +Los descendientes siempre son sustancialmente más cortos que el padre y +se colocan sustancialmente a la derecha. Un estilo muy usado es alinear +descendientes a un paréntesis de función abierto. + +Estas mismas reglas se aplican a los encabezados de funciones con una larga +lista de argumentos. + +Sin embargo, nunca rompa los strings visibles para el usuario, como los +mensajes printk, porque eso rompe la capacidad de grep a estos. + + +3) Colocación de llaves y espacios +---------------------------------- + +El otro problema que siempre surge en el estilo C es la colocación de +llaves. A diferencia del tamaño de la sangría, existen pocas razones +técnicas para elegir una estrategia de ubicación sobre la otra, pero la +forma preferida, como mostraron los profetas Kernighan y Ritchie, es poner +la llave de apertura en la línea, y colocar la llave de cierre primero, +así: + +.. code-block:: c + + if (x es verdad) { + hacemos y + } + +Esto se aplica a todos los bloques de declaraciones que no son funciones +(if, switch, for, while, do). Por ejemplo: + +.. code-block:: c + + switch (action) { + case KOBJ_ADD: + return "add"; + case KOBJ_REMOVE: + return "remove"; + case KOBJ_CHANGE: + return "change"; + default: + return NULL; + } + +Sin embargo, hay un caso especial, a saber, las funciones: tienen la llave +de apertura al comienzo de la siguiente línea, así: + +.. code-block:: c + + int funcion(int x) + { + cuerpo de la función + } + +Gente hereje de todo el mundo ha afirmado que esta inconsistencia es... +bueno... inconsistente, pero todas las personas sensatas saben que +(a) K&R tienen **razón** y (b) K&R tienen razón. Además, las funciones son +especiales de todos modos (no puede anidarlas en C). + +Tenga en cuenta que la llave de cierre está vacía en su línea propia, +**excepto** en los casos en que es seguida por una continuación de la misma +declaración, es decir, un ``while`` en una sentencia do o un ``else`` en +una sentencia if, como en: + +.. code-block:: c + + do { + cuerpo del bucle do + } while (condition); + +y + +.. code-block:: c + + if (x == y) { + .. + } else if (x > y) { + ... + } else { + .... + } + +Justificación: K&R. + +Además, tenga en cuenta que esta colocación de llaves también minimiza el +número de líneas vacías (o casi vacías), sin pérdida de legibilidad. Así, +como el suministro de nuevas líneas en su pantalla no es un recurso +renovable (piense en pantallas de terminal de 25 líneas), tienes más líneas +vacías para poner comentarios. + +No use llaves innecesariamente donde una sola declaración sea suficiente. + +.. code-block:: c + + if (condition) + accion(); + +y + +.. code-block:: none + + if (condición) + haz_esto(); + else + haz_eso(); + +Esto no aplica si solo una rama de una declaración condicional es una sola +declaración; en este último caso utilice llaves en ambas ramas: + +.. code-block:: c + + if (condición) { + haz_esto(); + haz_eso(); + } else { + en_otro_caso(); + } + +Además, use llaves cuando un bucle contenga más de una declaración simple: + +.. code-block:: c + + while (condición) { + if (test) + haz_eso(); + } + +3.1) Espacios +************* + +El estilo del kernel Linux para el uso de espacios depende (principalmente) +del uso de función versus uso de palabra clave. Utilice un espacio después +de (la mayoría de) las palabras clave. Las excepciones notables son sizeof, +typeof, alignof y __attribute__, que parecen algo así como funciones (y +generalmente se usan con paréntesis en Linux, aunque no son requeridos en +el idioma, como en: ``sizeof info`` después de que ``struct fileinfo info;`` +se declare). + +Así que use un espacio después de estas palabras clave:: + + if, switch, case, for, do, while + +pero no con sizeof, typeof, alignof, o __attribute__. Por ejemplo, + +.. code-block:: c + + + s = sizeof(struct file); + +No agregue espacios alrededor (dentro) de expresiones entre paréntesis. +Este ejemplo es **malo**: + +.. code-block:: c + + + s = sizeof( struct file ); + +Al declarar datos de puntero o una función que devuelve un tipo de puntero, +el uso preferido de ``*`` es adyacente al nombre del dato o nombre de la +función y no junto al nombre del tipo. Ejemplos: + +.. code-block:: c + + + char *linux_banner; + unsigned long long memparse(char *ptr, char **retptr); + char *match_strdup(substring_t *s); + +Use un espacio alrededor (a cada lado de) la mayoría de los operadores +binarios y ternarios, como cualquiera de estos:: + + = + - < > * / % | & ^ <= >= == != ? : + +pero sin espacio después de los operadores unarios:: + + & * + - ~ ! sizeof typeof alignof __attribute__ defined + +sin espacio antes de los operadores unarios de incremento y decremento del +sufijo:: + + ++ -- + +y sin espacio alrededor de los operadores de miembros de estructura ``.`` y +``->``. + +No deje espacios en blanco al final de las líneas. Algunos editores con +``inteligente`` sangría insertarán espacios en blanco al comienzo de las +nuevas líneas como sea apropiado, para que pueda comenzar a escribir la +siguiente línea de código de inmediato. Sin embargo, algunos de estos +editores no eliminan los espacios en blanco si finalmente no termina +poniendo una línea de código allí, como si dejara una línea en blanco. Como +resultado, termina con líneas que contienen espacios en blanco al final. + +Git le advertirá sobre los parches que introducen espacios en blanco al +final y puede, opcionalmente, eliminar los espacios en blanco finales por +usted; sin embargo, si se aplica una serie de parches, esto puede hacer que +los parches posteriores de la serie fallen al cambiar sus líneas de +contexto. + + +4) Nomenclatura +--------------- + +C es un lenguaje espartano, y sus convenciones de nomenclatura deberían +seguir su ejemplo. A diferencia de los programadores de Modula-2 y Pascal, +los programadores de C no usan nombres cuquis como +EstaVariableEsUnContadorTemporal. Un programador de C lo llamaría +variable ``tmp``, que es mucho más fácil de escribir, y no es mas difícil +de comprender. + +SIN EMBARGO, mientras que los nombres de mayúsculas y minúsculas están mal +vistos, los nombres descriptivos para las variables globales son +imprescindibles. Llamar a una función global ``foo`` es un delito. + +Una variable GLOBAL (para usar solo si **realmente** las necesita) necesita +tener un nombre descriptivo, al igual que las funciones globales. Si tiene +una función que cuenta el número de usuarios activos, debe llamar a esta +``contar_usuarios_activos()`` o similar, **no** debe llamarlo ``cntusr()``. + +Codificar el tipo de una función en el nombre (lo llamado notación húngara) +es estúpido: el compilador conoce los tipos de todos modos y puede +verificar estos, y solo confunde al programador. + +Los nombres de las variables LOCALES deben ser breves y directos. Si usted +tiene algún contador aleatorio de tipo entero, probablemente debería +llamarse ``i``. Llamarlo ``loop_counter`` no es productivo, si no hay +posibilidad de ser mal entendido. De manera similar, ``tmp`` puede ser casi +cualquier tipo de variable que se utiliza para contener un valor temporal. + +Si tiene miedo de mezclar los nombres de las variables locales, tiene otro +problema, que se denomina síndrome de +función-crecimiento-desequilibrio-de-hormona. Vea el capítulo 6 (Funciones). + +Para nombres de símbolos y documentación, evite introducir nuevos usos de +'master / slave' (maestro / esclavo) (o 'slave' independientemente de +'master') y 'lista negra / lista blanca' (backlist / whitelist). + +Los reemplazos recomendados para 'maestro / esclavo' son: + '{primary,main} / {secondary,replica,subordinate}' + '{initiator,requester} / {target,responder}' + '{controller,host} / {device,worker,proxy}' + 'leader / follower' + 'director / performer' + +Los reemplazos recomendados para 'backlist / whitelist' son: + 'denylist / allowlist' + 'blocklist / passlist' + +Las excepciones para la introducción de nuevos usos son mantener en espacio +de usuario una ABI/API, o al actualizar la especificación del código de un +hardware o protocolo existente (a partir de 2020) que requiere esos +términos. Para nuevas especificaciones, traduzca el uso de la terminología +de la especificación al estándar de código del kernel donde sea posible. + +5) Typedefs +----------- + +Por favor no use cosas como ``vps_t``. +Es un **error** usar typedef para estructuras y punteros. cuando ve un + +.. code-block:: c + + + vps_t a; + +en el código fuente, ¿qué significa? +En cambio, si dice + +.. code-block:: c + + struct virtual_container *a; + +puede decir qué es ``a`` en realidad. + +Mucha gente piensa que los typedefs ``ayudan a la legibilidad``. No. Son +útiles solamente para: + + (a) objetos totalmente opacos (donde el typedef se usa activamente para + **ocultar** cuál es el objeto). + + Ejemplo: ``pte_t`` etc. objetos opacos a los que solo puede acceder + usando las funciones de acceso adecuadas. + + .. note:: + + La opacidad y las ``funciones de acceso`` no son buenas por sí + mismas. La razón por la que los tenemos para cosas como pte_t, etc. + es que hay real y absolutamente **cero** información accesible de + forma portátil allí. + + (b) Tipos enteros claros, donde la abstracción **ayuda** a evitar + confusiones, ya sea ``int`` o ``long``. + + u8/u16/u32 son definiciones tipográficas perfectamente correctas + aunque encajan en la categoría (d) mejor que aquí. + + .. note:: + + De nuevo - debe haber una **razón** para esto. si algo es + ``unsigned long``, entonces no hay razón para hacerlo + + typedef unsigned long mis_flags_t; + + pero si hay una razón clara de por qué bajo ciertas circunstancias + podría ser un ``unsigned int`` y bajo otras configuraciones podría + ser ``unsigned long``, entonces, sin duda, adelante y use un typedef. + + (c) cuando lo use para crear literalmente un tipo **nuevo** para + comprobación de tipos. + + (d) Nuevos tipos que son idénticos a los tipos estándar C99, en ciertas + circunstancias excepcionales. + + Aunque sólo costaría un corto período de tiempo para los ojos y + cerebro para acostumbrarse a los tipos estándar como ``uint32_t``, + algunas personas se oponen a su uso de todos modos. + + Por lo tanto, los tipos ``u8/u16/u32/u64`` específicos de Linux y sus + equivalentes con signo, que son idénticos a los tipos estándar son + permitidos, aunque no son obligatorios en el nuevo código de su + elección. + + Al editar código existente que ya usa uno u otro conjunto de tipos, + debe ajustarse a las opciones existentes en ese código. + + (e) Tipos seguros para usar en el espacio de usuario. + + En ciertas estructuras que son visibles para el espacio de usuario, no + podemos requerir tipos C99 y o utilizat el ``u32`` anterior. Por lo + tanto, usamos __u32 y tipos similares en todas las estructuras que se + comparten con espacio de usuario. + +Tal vez también haya otros casos, pero la regla básicamente debería ser +NUNCA JAMÁS use un typedef a menos que pueda coincidir claramente con una +de estas reglas. + +En general, un puntero o una estructura que tiene elementos que pueden +ser razonablemente accedidos directamente, **nunca** deben ser un typedef. + +6) Funciones +------------ + +Las funciones deben ser cortas y dulces, y hacer una sola cosa. Deberían +caber en una o dos pantallas de texto (el tamaño de pantalla ISO/ANSI es +80x24, como todos sabemos), y hacer una cosa y hacerla bien. + +La longitud máxima de una función es inversamente proporcional a la +complejidad y el nivel de sangría de esa función. Entonces, si tiene una +función conceptualmente simple que es solo una larga (pero simple) +declaración de case, donde tiene que hacer un montón de pequeñas cosas para +un montón de diferentes casos, está bien tener una función más larga. + +Sin embargo, si tiene una función compleja y sospecha que un estudiante de +primer año de secundaria menos que dotado podría no comprender de qué se +trata la función, debe adherirse a los límites máximos tanto más de +cerca. Use funciones auxiliares con nombres descriptivos (puede pedirle al +compilador que los alinee si cree que es crítico para el rendimiento, y +probablemente lo hará mejor de lo que usted hubiera hecho). + +Otra medida de la función es el número de variables locales. Estas no deben +exceder de 5 a 10, o está haciendo algo mal. Piense de nuevo en la función +y divida en partes más pequeñas. Un cerebro humano puede generalmente +realiza un seguimiento de aproximadamente 7 cosas diferentes, cualquier +elemento más y se confunde. Usted sabe que es brillante, pero tal vez le +gustaría entender lo que hizo dentro de 2 semanas. + +En los archivos fuente, separe las funciones con una línea en blanco. Si la +función es exportada, la macro **EXPORT** debería ponerse inmediatamente +después de la función de cierre de línea de llave. Por ejemplo: + +.. code-block:: c + + int sistema_corriendo(void) + { + return estado_sistema == SISTEMA_CORRIENDO; + } + EXPORT_SYMBOL(sistema_corriendo); + +6.1) Prototipos de funciones +**************************** + +En los prototipos de funciones, incluya nombres de parámetros con sus tipos +de datos. Aunque esto no es requerido por el lenguaje C, se prefiere en +Linux porque es una forma sencilla de añadir información valiosa para el +lector. + +No utilice la palabra clave ``extern`` con declaraciones de función ya que +esto hace las líneas más largas y no es estrictamente necesario. + +Al escribir prototipos de funciones, mantenga el `orden de los elementos regular +`_. +Por ejemplo, usando este ejemplo de declaración de función:: + + __init void * __must_check action(enum magic value, size_t size, u8 count, + char *fmt, ...) __printf(4, 5) __malloc; + +El orden preferido de elementos para un prototipo de función es: + +- clase de almacenamiento (a continuación, ``static __always_inline``, + teniendo en cuenta que ``__always_inline`` es técnicamente un atributo + pero se trata como ``inline``) +- atributos de clase de almacenamiento (aquí, ``__init`` -- es decir, + declaraciones de sección, pero también cosas como ``__cold``) +- tipo de retorno (aquí, ``void *``) +- atributos de tipo de retorno (aquí, ``__must_check``) +- nombre de la función (aquí, ``action``) +- parámetros de la función (aquí, ``(enum magic value, size_t size, u8 count, char *fmt, ...)``, + teniendo en cuenta que los nombres de los parámetros siempre deben + incluirse) +- atributos de parámetros de función (aquí, ``__printf(4, 5)``) +- atributos de comportamiento de la función (aquí, ``__malloc``) + +Tenga en cuenta que para una **definición** de función (es decir, el cuerpo +real de la función), el compilador no permite atributos de parámetros de +función después de parámetros de la función. En estos casos, deberán ir +tras los atributos de clase (por ejemplo, tenga en cuenta el cambio de +posición de ``__printf(4, 5)`` a continuación, en comparación con el +ejemplo de **declaración** anterior):: + + static __always_inline __init __printf(4, 5) void * __must_check action(enum magic value, + size_t size, u8 count, char *fmt, ...) __malloc + { + ... + } + +7) Salida centralizada de funciones +----------------------------------- + +Aunque desaprobado por algunas personas, el equivalente de la instrucción +goto es utilizado con frecuencia por los compiladores, en forma de +instrucción de salto incondicional. + +La declaración goto es útil cuando una función sale desde múltiples +ubicaciones y se deben realizar algunos trabajos comunes, como la limpieza. +Si no se necesita limpieza, entonces simplemente haga return directamente. + +Elija nombres de etiquetas que digan qué hace el goto o por qué existe el +goto. Un ejemplo de un buen nombre podría ser ``out_free_buffer:`` +(``salida_liberar_buffer``) si al irse libera ``buffer``. Evite usar +nombres GW-BASIC como ``err1:`` y ``err2:``, ya que tendría que volver a +numerarlos si alguna vez agrega o elimina rutas de salida, y hacen que sea +difícil de verificar que sean correctos, de todos modos. + +La razón para usar gotos es: + +- Las declaraciones incondicionales son más fáciles de entender y seguir. +- se reduce el anidamiento +- errores al no actualizar los puntos de salida individuales al hacer + modificaciones son evitados +- ahorra el trabajo del compilador de optimizar código redundante ;) + +.. code-block:: c + + int fun(int a) + { + int result = 0; + char *buffer; + + buffer = kmalloc(SIZE, GFP_KERNEL); + if (!buffer) + return -ENOMEM; + + if (condition1) { + while (loop1) { + ... + } + result = 1; + goto out_free_buffer; + } + ... + out_free_buffer: + kfree(buffer); + return result; + } + +Un tipo común de error a tener en cuenta es "un error de error" que es algo +así: + +.. code-block:: c + + err: + kfree(foo->bar); + kfree(foo); + return ret; + +El error en este código es que en algunas rutas de salida, ``foo`` es NULL. +Normalmente la solución para esto es dividirlo en dos etiquetas de error +``err_free_bar:`` y ``err_free_foo:``: + +.. code-block:: c + + err_free_bar: + kfree(foo->bar); + err_free_foo: + kfree(foo); + return ret; + +Idealmente, debería simular errores para probar todas las rutas de salida. + + +8) Comentarios +-------------- + +Los comentarios son buenos, pero también existe el peligro de comentar +demasiado. NUNCA trate de explicar CÓMO funciona su código en un +comentario: es mucho mejor escribir el código para que el +**funcionamiento** sea obvio y es una pérdida de tiempo explicar código mal +escrito. + +Generalmente, desea que sus comentarios digan QUÉ hace su código, no CÓMO. +Además, trate de evitar poner comentarios dentro del cuerpo de una función: +si la función es tan compleja que necesita comentar por separado partes de +esta, probablemente debería volver al capítulo 6 una temporada. Puede +hacer pequeños comentarios para notar o advertir sobre algo particularmente +inteligente (o feo), pero trate de evitar el exceso. En su lugar, ponga los +comentarios al principio de la función, diga a la gente lo que hace y +posiblemente POR QUÉ hace esto. + +Al comentar las funciones de la API del kernel, utilice el formato +kernel-doc. Consulte los archivos en :ref:`Documentation/doc-guide/ ` +y ``scripts/kernel-doc`` para más detalles. + +El estilo preferido para comentarios largos (de varias líneas) es: + +.. code-block:: c + + /* + * Este es el estilo preferido para comentarios + * multilínea en el código fuente del kernel Linux. + * Por favor, utilícelo constantemente. + * + * Descripción: Una columna de asteriscos en el lado izquierdo, + * con líneas iniciales y finales casi en blanco. + */ + +Para archivos en net/ y drivers/net/, el estilo preferido para comentarios +largos (multi-linea) es un poco diferente. + +.. code-block:: c + + /* El estilo de comentario preferido para archivos en net/ y drivers/net + * se asemeja a esto. + * + * Es casi lo mismo que el estilo de comentario generalmente preferido, + * pero no hay una línea inicial casi en blanco. + */ + +También es importante comentar los datos, ya sean tipos básicos o +derivados. Para este fin, use solo una declaración de datos por línea (sin +comas para múltiples declaraciones de datos). Esto le deja espacio para un +pequeño comentario sobre cada elemento, explicando su uso. + +9) Has hecho un desastre +--------------------------- + +Está bien, todos lo hacemos. Probablemente un antiguo usuario de Unix le +haya dicho que ``GNU emacs`` formatea automáticamente las fuentes C por +usted, y ha notado que sí, lo hace, pero los por defecto que tiene son +menos que deseables (de hecho, son peores que los aleatorios) escribiendo - +un número infinito de monos escribiendo en GNU emacs nunca harán un buen +programa). + +Por lo tanto, puede deshacerse de GNU emacs o cambiarlo y usar valores más +sanos. Para hacer esto último, puede pegar lo siguiente en su archivo +.emacs: + +.. code-block:: none + + (defun c-lineup-arglist-tabs-only (ignored) + "Line up argument lists by tabs, not spaces" + (let* ((anchor (c-langelem-pos c-syntactic-element)) + (column (c-langelem-2nd-pos c-syntactic-element)) + (offset (- (1+ column) anchor)) + (steps (floor offset c-basic-offset))) + (* (max steps 1) + c-basic-offset))) + + (dir-locals-set-class-variables + 'linux-kernel + '((c-mode . ( + (c-basic-offset . 8) + (c-label-minimum-indentation . 0) + (c-offsets-alist . ( + (arglist-close . c-lineup-arglist-tabs-only) + (arglist-cont-nonempty . + (c-lineup-gcc-asm-reg c-lineup-arglist-tabs-only)) + (arglist-intro . +) + (brace-list-intro . +) + (c . c-lineup-C-comments) + (case-label . 0) + (comment-intro . c-lineup-comment) + (cpp-define-intro . +) + (cpp-macro . -1000) + (cpp-macro-cont . +) + (defun-block-intro . +) + (else-clause . 0) + (func-decl-cont . +) + (inclass . +) + (inher-cont . c-lineup-multi-inher) + (knr-argdecl-intro . 0) + (label . -1000) + (statement . 0) + (statement-block-intro . +) + (statement-case-intro . +) + (statement-cont . +) + (substatement . +) + )) + (indent-tabs-mode . t) + (show-trailing-whitespace . t) + )))) + + (dir-locals-set-directory-class + (expand-file-name "~/src/linux-trees") + 'linux-kernel) + +Esto hará que emacs funcione mejor con el estilo de código del kernel para +C en archivos bajo ``~/src/linux-trees``. + +Pero incluso si no logra que emacs realice un formateo correcto, no todo +está perdido: use ``indent``. + +Ahora bien, de nuevo, la sangría de GNU tiene la misma configuración de +muerte cerebral que GNU emacs tiene, por lo que necesita darle algunas +opciones de línea de comando. Sin embargo, eso no es tan malo, porque +incluso los creadores de GNU indent reconocen la autoridad de K&R (la gente +de GNU no es mala, solo están gravemente equivocados en este asunto), por +lo que simplemente de a la sangría las opciones ``-kr -i8`` (significa +``K&R, guiones de 8 caracteres``), o use ``scripts/Lindent``, que indenta +con ese estilo. + +``indent`` tiene muchas opciones, y especialmente cuando se trata de +comentar reformateos, es posible que desee echar un vistazo a la página del +manual. Pero recuerde: ``indent`` no es la solución para una mala +programación. + +Tenga en cuenta que también puede usar la herramienta ``clang-format`` para +ayudarlo con estas reglas, para volver a formatear rápidamente partes de su +código automáticamente, y revisar archivos completos para detectar errores +de estilo del código, errores tipográficos y posibles mejoras. También es +útil para ordenar ``#includes``, para alinear variables/macros, para +redistribuir texto y otras tareas similares. Vea el archivo +:ref:`Documentation/process/clang-format.rst ` para más +detalles. + +10) Archivos de configuración de Kconfig +---------------------------------------- + +Para todos los archivos de configuración de Kconfig* en todo el árbol +fuente, la sangría es algo diferente. Las líneas bajo una definición +``config`` están indentadas con una tabulación, mientras que el texto de +ayuda tiene una sangría adicional de dos espacios. Ejemplo:: + + config AUDIT + bool "Soporte para auditar" + depends on NET + help + Habilita la infraestructura de auditoría que se puede usar con otro + subsistema kernel, como SELinux (que requiere esto para + registro de salida de mensajes avc). No hace auditoría de llamadas al + sistema sin CONFIG_AUDITSYSCALL. + +Características seriamente peligrosas (como soporte de escritura para +ciertos filesystems) deben anunciar esto de forma destacada en su cadena de +solicitud:: + + config ADFS_FS_RW + bool "ADFS write support (DANGEROUS)" + depends on ADFS_FS + ... + +Para obtener la documentación completa sobre los archivos de configuración, +consulte el archivo Documentation/kbuild/kconfig-language.rst. + + +11) Estructuras de datos +------------------------ + +Las estructuras de datos que tienen visibilidad fuera del contexto de un +solo subproceso en el que son creadas y destruidas, siempre debe tener +contadores de referencia. En el kernel, la recolección de basura no existe +(y fuera, la recolección de basura del kernel es lenta e ineficiente), lo +que significa que absolutamente **tiene** para hacer referencia y contar +todos sus usos. + +El conteo de referencias significa que puede evitar el bloqueo y permite +que múltiples usuarios tengan acceso a la estructura de datos en paralelo - +y no tengan que preocuparse de que la estructura, de repente, desaparezca +debajo de su control, solo porque durmieron o hicieron otra cosa por un +tiempo. + +Tenga en cuenta que el bloqueo **no** reemplaza el recuento de referencia. +El bloqueo se utiliza para mantener la coherencia de las estructuras de +datos, mientras que la referencia y contar es una técnica de gestión de +memoria. Por lo general, ambos son necesarios, y no deben confundirse entre +sí. + +De hecho, muchas estructuras de datos pueden tener dos niveles de conteo de +referencias, cuando hay usuarios de diferentes ``clases``. El conteo de +subclases cuenta el número de usuarios de la subclase y disminuye el conteo +global solo una vez, cuando el recuento de subclases llega a cero. + +Se pueden encontrar ejemplos de este tipo de ``recuento de referencias de +niveles múltiples`` en la gestión de memoria (``struct mm_struct``: +mm_users y mm_count), y en código del sistema de archivos +(``struct super_block``: s_count y s_active). + +Recuerde: si otro hilo puede encontrar su estructura de datos y usted no +tiene un recuento de referencias, es casi seguro que tiene un error. + +12) Macros, Enums y RTL +------------------------ + +Los nombres de macros que definen constantes y etiquetas en enumeraciones +(enums) están en mayúsculas. + +.. code-block:: c + + #define CONSTANTE 0x12345 + +Se prefieren los enums cuando se definen varias constantes relacionadas. + +Se aprecian los nombres de macro en MAYÚSCULAS, pero las macros que se +asemejan a funciones puede ser nombradas en minúscula. + +Generalmente, las funciones en línea son preferibles a las macros que se +asemejan a funciones. + +Las macros con varias instrucciones deben contenerse en un bloque do-while: + +.. code-block:: c + + #define macrofun(a, b, c) \ + do { \ + if (a == 5) \ + haz_esto(b, c); \ + } while (0) + +Cosas a evitar al usar macros: + +1) macros que afectan el flujo de control: + +.. code-block:: c + + #define FOO(x) \ + do { \ + if (blah(x) < 0) \ + return -EBUGGERED; \ + } while (0) + +es una **muy** mala idea. Parece una llamada de función pero sale de la +función de ``llamada``; no rompa los analizadores internos de aquellos que +leerán el código. + +2) macros que dependen de tener una variable local con un nombre mágico: + +.. code-block:: c + + #define FOO(val) bar(index, val) + +puede parecer algo bueno, pero es confuso como el infierno cuando uno lee +el código, y es propenso a romperse por cambios aparentemente inocentes. + +3) macros con argumentos que se usan como valores l: FOO(x) = y; le van +a morder si alguien, por ejemplo, convierte FOO en una función en línea. + +4) olvidarse de la precedencia: las macros que definen constantes usando +expresiones deben encerrar la expresión entre paréntesis. Tenga cuidado con +problemas similares con macros usando parámetros. + +.. code-block:: c + + #define CONSTANTE 0x4000 + #define CONSTEXP (CONSTANTE | 3) + +5) colisiones de espacio de nombres ("namespace") al definir variables +locales en macros que se asemejan a funciones: + +.. code-block:: c + + #define FOO(x) \ + ({ \ + typeof(x) ret; \ + ret = calc_ret(x); \ + (ret); \ + }) + +ret es un nombre común para una variable local -es menos probable que +__foo_ret colisione (coincida) con una variable existente. + +El manual de cpp trata las macros de forma exhaustiva. El manual interno de +gcc también cubre RTL, que se usa frecuentemente con lenguaje ensamblador +en el kernel. + +13) Imprimir mensajes del kernel +-------------------------------- + +A los desarrolladores del kernel les gusta ser vistos como alfabetizados. +Cuide la ortografía de los mensajes del kernel para causar una buena +impresión. No utilice contracciones incorrectas como ``dont``; use +``do not`` o ``don't`` en su lugar. Haga sus mensajes concisos, claros e +inequívocos. + +Los mensajes del kernel no tienen que terminar con un punto. + +Imprimir números entre paréntesis (%d) no agrega valor y debe evitarse. + +Hay varias modelos de macros de diagnóstico de driver en +que debe usar para asegurarse de que los mensajes coincidan con el +dispositivo correcto y driver, y están etiquetados con el nivel correcto: +dev_err(), dev_warn(), dev_info(), y así sucesivamente. Para mensajes que +no están asociados con un dispositivo particular, define +pr_notice(), pr_info(), pr_warn(), pr_err(), etc. + +Crear buenos mensajes de depuración puede ser todo un desafío; y una vez +los tiene, pueden ser de gran ayuda para la resolución remota de problemas. +Sin embargo, la impresión de mensajes de depuración se maneja de manera +diferente a la impresión de otros mensajes que no son de depuración. +Mientras que las otras funciones pr_XXX() se imprimen incondicionalmente, +pr_debug() no lo hace; se compila fuera por defecto, a menos que DEBUG sea +definido o se establezca CONFIG_DYNAMIC_DEBUG. Eso es cierto para dev_dbg() +también, y una convención relacionada usa VERBOSE_DEBUG para agregar +mensajes dev_vdbg() a los ya habilitados por DEBUG. + +Muchos subsistemas tienen opciones de depuración de Kconfig para activar +-DDEBUG en el Makefile correspondiente; en otros casos, los archivos +usan #define DEBUG. Y cuando un mensaje de depuración debe imprimirse +incondicionalmente, por ejemplo si es ya dentro de una sección #ifdef +relacionada con la depuración, printk(KERN_DEBUG ...) puede ser usado. + +14) Reservando memoria +---------------------- + +El kernel proporciona los siguientes asignadores de memoria de propósito +general: kmalloc(), kzalloc(), kmalloc_array(), kcalloc(), vmalloc() y +vzalloc(). Consulte la documentación de la API para obtener más información. +a cerca de ellos. :ref:`Documentation/core-api/memory-allocation.rst +` + +La forma preferida para pasar el tamaño de una estructura es la siguiente: + +.. code-block:: c + + p = kmalloc(sizeof(*p), ...); + +La forma alternativa donde se deletrea el nombre de la estructura perjudica +la legibilidad, y presenta una oportunidad para un error cuando se cambia +el tipo de variable de puntero, pero el tamaño correspondiente de eso que +se pasa a un asignador de memoria no. + +Convertir el valor devuelto, que es un puntero vacío, es redundante. La +conversión desde el puntero vacío a cualquier otro tipo de puntero está +garantizado por la programación en idioma C. + +La forma preferida para asignar una matriz es la siguiente: + +.. code-block:: c + + p = kmalloc_array(n, sizeof(...), ...); + +La forma preferida para asignar una matriz a cero es la siguiente: + +.. code-block:: c + + p = kcalloc(n, sizeof(...), ...); + +Ambos casos verifican el desbordamiento en el tamaño de asignación n * +sizeof (...), y devuelven NULL si esto ocurrió. + +Todas estas funciones de asignación genéricas emiten un volcado de pila +(" stack dump") en caso de fallo cuando se usan sin __GFP_NOWARN, por lo +que no sirve de nada emitir un mensaje de fallo adicional cuando se +devuelva NULL. + +15) La enfermedad de inline +---------------------------- + +Parece haber una común percepción errónea de que gcc tiene una magica +opción "hazme más rápido" de aceleración, llamada ``inline`` (en línea). +Mientras que el uso de inlines puede ser apropiado (por ejemplo, como un +medio para reemplazar macros, consulte el Capítulo 12), muy a menudo no lo +es. El uso abundante de la palabra clave inline conduce a una mayor kernel, +que a su vez ralentiza el sistema en su conjunto, debido a una mayor huella +de icache para la CPU, y sencillamente porque hay menos memoria disponible +para el pagecache. Solo piense en esto; un fallo en la memoria caché de la +página provoca una búsqueda de disco, que tarda fácilmente 5 milisegundos. +Hay MUCHOS ciclos de CPU que puede entrar en estos 5 milisegundos. + +Una razonable regla general es no poner funciones inline que tengan más de +3 líneas de código en ellas. Una excepción a esta regla son los casos en +que se sabe que un parámetro es una constante en tiempo de compilación, y +como resultado de esto, usted *sabe*, el compilador podrá optimizar la +mayor parte de su función en tiempo de compilación. Para un buen ejemplo de +este último caso, véase la función en línea kmalloc(). + +A menudo, la gente argumenta que agregar funciones en línea que son +estáticas y se usan solo una vez, es siempre una victoria ya que no hay +perdida de espacio. Mientras esto es técnicamente correcto, gcc es capaz de +incorporarlos automáticamente sin ayuda, y esta el problema de +mantenimiento de eliminar el inline, cuando un segundo usuario supera el +valor potencial de la pista que le dice a gcc que haga algo que habría +hecho de todos modos. + +16) Valores devueltos por función y sus nombres +----------------------------------------------- + +Las funciones pueden devolver valores de muchos tipos diferentes, y uno de +lo más común es un valor que indica si la función tuvo éxito o ha fallado. +Dicho valor se puede representar como un número entero de código de error +(-Exxx = falla, 0 = éxito) o un booleano ``con éxito`` (0 = falla, distinto +de cero = éxito). + +La mezcla de estos dos tipos de representaciones es una fuente fértil de +errores difíciles de encontrar. Si el lenguaje C incluyera una fuerte +distinción entre enteros y booleanos, el compilador encontraría estos +errores por nosotros... pero no lo hace. Para ayudar a prevenir tales +errores, siga siempre esta convención:: + + Si el nombre de una función es una acción o un comando imperativo, + la función debe devolver un número entero de código de error. si el nombre + es un predicado, la función debe devolver un valor booleano "exitoso". + +Por ejemplo, ``agregar trabajo`` es un comando, y la función +agregar_trabajo() devuelve 0 en caso de éxito o -EBUSY en caso de fracaso. +De la misma manera, ``dispositivo PCI presente`` es un predicado, y la +función pci_dev_present() devuelve 1 si tiene éxito en encontrar un +dispositivo coincidente o 0 si no es así. + +Todas las funciones EXPORTed (exportadas) deben respetar esta convención, +al igual que todas las funciones publicas. Las funciones privadas +(estáticas) no lo necesitan, pero es recomendado que lo hagan. + +Las funciones cuyo valor devuelto es el resultado real de un cálculo, en +lugar de una indicación de si el cómputo tuvo éxito, no están sujetas a +esta regla. Generalmente indican fallo al devolver valores fuera del rango +de resultados. Los ejemplos típicos serían funciones que devuelven +punteros; estos usan NULL o el mecanismo ERR_PTR para informar de fallos. + +17) Usando bool +---------------- + +El tipo bool del kernel Linux es un alias para el tipo C99 _Bool. Los +valores booleanos pueden solo evaluar a 0 o 1, y la conversión implícita o +explícita a bool convierte automáticamente el valor en verdadero o falso. +Cuando se utilizan tipos booleanos, +!! no se necesita construcción, lo que elimina una clase de errores. + +Cuando se trabaja con valores booleanos, se deben usar las definiciones +verdadera y falsa, en lugar de 1 y 0. + +Los tipos de devolución de función bool y las variables de pila siempre +se pueden usar cuando esto sea adecuado. Se recomienda el uso de bool para +mejorar la legibilidad y, a menudo, es una mejor opción que 'int' para +almacenar valores booleanos. + +No use bool si el diseño de la línea de caché o el tamaño del valor son +importantes, ya que su tamaño y la alineación varía según la arquitectura +compilada. Las estructuras que son optimizadas para la alineación y el +tamaño no debe usar bool. + +Si una estructura tiene muchos valores verdadero/falso, considere +consolidarlos en un bitfield con miembros de 1 bit, o usando un tipo de +ancho fijo apropiado, como u8. + +De manera similar, para los argumentos de función, se pueden consolidar +muchos valores verdaderos/falsos en un solo argumento bit a bit 'flags' y +'flags' a menudo, puede ser una alternativa de argumento más legible si los +sitios de llamada tienen constantes desnudas de tipo verdaderas/falsas. + +De lo contrario, el uso limitado de bool en estructuras y argumentos puede +mejorar la legibilidad. + +18) No reinvente las macros del kernel +--------------------------------------- + +El archivo de cabecera include/linux/kernel.h contiene una serie de macros +que debe usar, en lugar de programar explícitamente alguna variante de +estos por usted mismo. Por ejemplo, si necesita calcular la longitud de una +matriz, aproveche la macro + +.. code-block:: c + + #define ARRAY_SIZE(x) (sizeof(x) / sizeof((x)[0])) + +De manera similar, si necesita calcular el tamaño de algún miembro de la +estructura, use + +.. code-block:: c + + #define sizeof_field(t, f) (sizeof(((t*)0)->f)) + +También hay macros min() y max() que realizan una verificación estricta de +tipos si lo necesita. Siéntase libre de leer detenidamente ese archivo de +encabezado para ver qué más ya está definido y que no debe reproducir en su +código. + +19) Editores modeline y otros desastres +--------------------------------------- + +Algunos editores pueden interpretar la información de configuración +incrustada en los archivos fuente, indicado con marcadores especiales. Por +ejemplo, emacs interpreta las líneas marcadas como esto: + +.. code-block:: c + + -*- mode: c -*- + +O así: + +.. code-block:: c + + /* + Local Variables: + compile-command: "gcc -DMAGIC_DEBUG_FLAG foo.c" + End: + */ + +Vim interpreta los marcadores que se ven así: + +.. code-block:: c + + /* vim:set sw=8 noet */ + +No incluya ninguno de estos en los archivos fuente. La gente tiene sus +propias configuraciones del editor, y sus archivos de origen no deben +anularlos. Esto incluye marcadores para sangría y configuración de modo. +La gente puede usar su propio modo personalizado, o puede tener algún otro +método mágico para que la sangría funcione correctamente. + + +20) Ensamblador inline +----------------------- + +En el código específico de arquitectura, es posible que deba usar +ensamblador en línea para interactuar con funcionalidades de CPU o +plataforma. No dude en hacerlo cuando sea necesario. Sin embargo, no use +ensamblador en línea de forma gratuita cuando C puede hacer el trabajo. +Puede y debe empujar el hardware desde C cuando sea posible. + +Considere escribir funciones auxiliares simples que envuelvan bits comunes +de ensamblador, en lugar de escribirlos repetidamente con ligeras +variaciones. Recuerde que el ensamblador en línea puede usar parámetros C. + +Las funciones de ensamblador grandes y no triviales deben ir en archivos .S, +con su correspondientes prototipos de C definidos en archivos de encabezado +en C. Los prototipos de C para el ensamblador deben usar ``asmlinkage``. + +Es posible que deba marcar su declaración asm como volátil, para evitar que +GCC la elimine si GCC no nota ningún efecto secundario. No siempre es +necesario hacerlo, sin embargo, y hacerlo innecesariamente puede limitar la +optimización. + +Al escribir una sola declaración de ensamblador en línea que contiene +múltiples instrucciones, ponga cada instrucción en una línea separada en +una string separada, y termine cada string excepto la última con ``\n\t`` +para indentar correctamente la siguiente instrucción en la salida en +ensamblador: + +.. code-block:: c + + asm ("magic %reg1, #42\n\t" + "more_magic %reg2, %reg3" + : /* outputs */ : /* inputs */ : /* clobbers */); + +21) Compilación condicional +--------------------------- + +Siempre que sea posible, no use condicionales de preprocesador (#if, +#ifdef) en archivos .c; de lo contrario, el código es más difícil de leer y +la lógica más difícil de seguir. En cambio, use dichos condicionales en un +archivo de encabezado que defina funciones para usar en esos archivos .c, +proporcionando versiones de código auxiliar sin operación en el caso #else, +y luego llame a estas funciones incondicionalmente desde archivos .c. El +compilador evitará generar cualquier código para las llamadas restantes, +produciendo resultados idénticos, pero la lógica es fácil de seguir. + +Prefiera compilar funciones completas, en lugar de porciones de funciones o +porciones de expresiones. En lugar de poner un ifdef en una expresión, +divida la totalidad de la expresión con una función de ayuda independiente +y aplique el condicional a esa función. + +Si tiene una función o variable que puede potencialmente quedar sin usar en +una configuración en particular, y el compilador advertiría sobre su +definición sin usar, marque la definición como __maybe_unused en lugar de +envolverla en un preprocesador condicional. (Sin embargo, si una función o +variable *siempre* acaba sin ser usada, bórrela.) + +Dentro del código, cuando sea posible, use la macro IS_ENABLED para +convertir un símbolo Kconfig en una expresión booleana de C, y utilícelo en +un condicional de C normal: + +.. code-block:: c + + if (IS_ENABLED(CONFIG_SOMETHING)) { + ... + } + +El compilador "doblará"" constantemente el condicional e incluirá o +excluirá el bloque de código al igual que con un #ifdef, por lo que esto no +agregará ningún tiempo de gastos generales en ejecución. Sin embargo, este +enfoque todavía permite que el compilador de C vea el código dentro del +bloque, y verifique que sea correcto (sintaxis, tipos, símbolo, referencias, +etc.). Por lo tanto, aún debe usar un #ifdef si el código dentro del bloque +hace referencia a símbolos que no existirán si no se cumple la condición. + +Al final de cualquier bloque #if o #ifdef no trivial (más de unas pocas +líneas), incluya un comentario después de #endif en la misma línea, +anotando la expresión condicional utilizada. Por ejemplo: + +.. code-block:: c + + #ifdef CONFIG_SOMETHING + ... + #endif /* CONFIG_SOMETHING */ + +22) No rompa el kernel +----------------------- + +En general, la decisión de romper el kernel pertenece al usuario, más que +al desarrollador del kernel. + +Evite el panic() +**************** + +panic() debe usarse con cuidado y principalmente solo durante el arranque +del sistema. panic() es, por ejemplo, aceptable cuando se queda sin memoria +durante el arranque y no puede continuar. + +Use WARN() en lugar de BUG() +**************************** + +No agregue código nuevo que use cualquiera de las variantes BUG(), como +BUG(), BUG_ON() o VM_BUG_ON(). En su lugar, use una variante WARN*(), +preferiblemente WARN_ON_ONCE(), y posiblemente con código de recuperación. +El código de recuperación no es requerido si no hay una forma razonable de +recuperar, al menos parcialmente. + +"Soy demasiado perezoso para tener en cuenta los errores" no es una excusa +para usar BUG(). Importantes corrupciones internas sin forma de continuar +aún pueden usar BUG(), pero necesitan una buena justificación. + +Use WARN_ON_ONCE() en lugar de WARN() o WARN_ON() +************************************************* + +Generalmente, se prefiere WARN_ON_ONCE() a WARN() o WARN_ON(), porque es +común que una condición de advertencia dada, si ocurre, ocurra varias +veces. Esto puede llenar el registro del kernel, e incluso puede ralentizar +el sistema lo suficiente como para que el registro excesivo se convierta en +su propio, adicional problema. + +No haga WARN a la ligera +************************ + +WARN*() está diseñado para situaciones inesperadas que nunca deberían +suceder. Las macros WARN*() no deben usarse para nada que se espera que +suceda durante un funcionamiento normal. No hay "checkeos" previos o +posteriores a la condición, por ejemplo. De nuevo: WARN*() no debe usarse +para una condición esperada que vaya a activarse fácilmente, por ejemplo, +mediante acciones en el espacio del usuario. pr_warn_once() es una +alternativa posible, si necesita notificar al usuario de un problema. + +No se preocupe sobre panic_on_warn de usuarios +********************************************** + +Algunas palabras más sobre panic_on_warn: Recuerde que ``panic_on_warn`` es +una opción disponible del kernel, y que muchos usuarios configuran esta +opción. Esta es la razón por la que hay un artículo de "No haga WARN a la +ligera", arriba. Sin embargo, la existencia de panic_on_warn de usuarios no +es una razón válida para evitar el uso juicioso de WARN*(). Esto se debe a +que quien habilita panic_on_warn, explícitamente pidió al kernel que +fallara si se dispara un WARN*(), y tales usuarios deben estar preparados +para afrontar las consecuencias de un sistema que es algo más probable que +se rompa. + +Use BUILD_BUG_ON() para aserciones en tiempo de compilación +*********************************************************** + +El uso de BUILD_BUG_ON() es aceptable y recomendado, porque es una aserción +en tiempo de compilación, que no tiene efecto en tiempo de ejecución. + +Apéndice I) Referencias +----------------------- + +The C Programming Language, Segunda edicion +por Brian W. Kernighan and Dennis M. Ritchie. +Prentice Hall, Inc., 1988. +ISBN 0-13-110362-8 (paperback), 0-13-110370-9 (hardback). + +The Practice of Programming +por Brian W. Kernighan and Rob Pike. +Addison-Wesley, Inc., 1999. +ISBN 0-201-61586-X. + +manuales GCC - en cumplimiento con K&R y este texto - para cpp, gcc, +detalles de gcc y sangría, todo disponible en https://www.gnu.org/manual/ + +WG14 es el grupo de trabajo de estandarización internacional de la +programación en lenguaje C, URL: http://www.open-std.org/JTC1/SC22/WG14/ + +:ref:`process/coding-style.rst ` del kernel, por greg@kroah.com at OLS 2002: +http://www.kroah.com/linux/talks/ols_2002_kernel_codingstyle_talk/html/ diff --git a/Documentation/translations/sp_SP/process/index.rst b/Documentation/translations/sp_SP/process/index.rst index 4acb7f5005af..49a05f6a5544 100644 --- a/Documentation/translations/sp_SP/process/index.rst +++ b/Documentation/translations/sp_SP/process/index.rst @@ -12,3 +12,4 @@ submitting-patches kernel-docs + coding-style