From patchwork Tue Jul 27 04:52:22 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Tudor Ambarus X-Patchwork-Id: 12401907 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-17.5 required=3.0 tests=BAYES_00,DKIMWL_WL_HIGH, DKIM_SIGNED,DKIM_VALID,HEADER_FROM_DIFFERENT_DOMAINS,INCLUDES_CR_TRAILER, INCLUDES_PATCH,MAILING_LIST_MULTI,SPF_HELO_NONE,SPF_PASS,URIBL_BLOCKED, USER_AGENT_GIT autolearn=unavailable autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id A6F10C4338F for ; Tue, 27 Jul 2021 07:14:24 +0000 (UTC) Received: from bombadil.infradead.org (bombadil.infradead.org [198.137.202.133]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mail.kernel.org (Postfix) with ESMTPS id 6B5D361185 for ; Tue, 27 Jul 2021 07:14:24 +0000 (UTC) DMARC-Filter: OpenDMARC Filter v1.4.1 mail.kernel.org 6B5D361185 Authentication-Results: mail.kernel.org; dmarc=fail (p=quarantine dis=none) header.from=microchip.com Authentication-Results: mail.kernel.org; spf=none smtp.mailfrom=lists.infradead.org DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=lists.infradead.org; s=bombadil.20210309; h=Sender: Content-Transfer-Encoding:Content-Type:Cc:List-Subscribe:List-Help:List-Post: List-Archive:List-Unsubscribe:List-Id:MIME-Version:References:In-Reply-To: Message-ID:Date:Subject:To:From:Reply-To:Content-ID:Content-Description: Resent-Date:Resent-From:Resent-Sender:Resent-To:Resent-Cc:Resent-Message-ID: List-Owner; bh=vcsFB5Yfn2D8B56ItALfmoH5tQGXV5Ll4tKmc79qkY8=; b=33lVjZud2CpVRN 2jWsBBs8JhkGcorSft0fnawZmujXFGxJj7cVrPsOvgyEfG1iGf1IQm5/fw7MNxv6OHt1Gurgc6wd/ JIOe8Jw89LHQnOrfTPrSuWLPExkVYBMJCA+sJ2IZvYg9adopwMeWrHkLE9IKeK8A5WRw2/c+2P1sz oTF9IpgIHOFUj0Ac6S4B5aEeoJRCFrY+iyFJtMvgBGAISgc71kjMDfGtpOWMwFrTdG+eWfcxcI8Nv fFL+V3SCewrj0ut+j8GCuskoxAv/TakTkaTSeGD+yFl6RL2RRNajvYRGSLE/L9js3k4lrdz2y3nNc WsulWijCzTgJE2oKqz3A==; Received: from localhost ([::1] helo=bombadil.infradead.org) by bombadil.infradead.org with esmtp (Exim 4.94.2 #2 (Red Hat Linux)) id 1m8HFd-00DlG6-Um; Tue, 27 Jul 2021 07:11:43 +0000 Received: from esa.microchip.iphmx.com ([68.232.154.123]) by bombadil.infradead.org with esmtps (Exim 4.94.2 #2 (Red Hat Linux)) id 1m8F7p-00DIA3-4T; Tue, 27 Jul 2021 04:55:30 +0000 DKIM-Signature: v=1; a=rsa-sha256; c=simple/simple; d=microchip.com; i=@microchip.com; q=dns/txt; s=mchp; t=1627361728; x=1658897728; h=from:to:cc:subject:date:message-id:in-reply-to: references:mime-version:content-transfer-encoding; bh=SzwolEeGEyf9oVitKoVWHbwOtUaC9B7RoDUDxRyncSM=; b=rlKWhOZFnwdk2liwM/fwltwflE3Tos+Lfo9dDFjtS6y2z+Y352FatF53 im6Y2UTKiRH0HK/0a32RljRFeOh8EVSs5WIkgQBIfkqqgLMfg/3iDQVva iudxhwimM0uoc30ppx/o6NvmwIIEPtVl2jX66be+hJ1x5KoIVKYf2lKSd pEpNhtxITaZqT9gaP8Mde749JHzPEhCau+pz6uVekF8tyzyXuBpOPMq3v Puy37oD1PtHng+wCa+796bXSUjDs6P/Sw4tOjgoBYrduaNtLvAqQGKD3b VRQzI4kDirDulGzopb6r0Q+59loFXb32IVRxlLj3nYsQmfxz/RrBv4+Tf g==; IronPort-SDR: 9XNm7nmNa6fpHsh9VcPRvZQ4yZM2IpARhmTgovzXaLol2YVXizopAqpcep/oIfGSOkYq1QpWXB OWFtvjkqDY+95OtH6lAz1HrOuOvXYt8004GcmzhIn6jTgSUnI4WJ/gdh6cJS9PbD/VCIMnuZZe OcHXZ74pnFCxMpOdKPFRWWVK4WFA02xtu/Ppgch3eOyi5/gXGwBcfrhBeTIeAdlVbIg+VyS+Gr OjFAq/rn6sJAVhtMe/bNkyUJe4mexn86Aewqr4bazgaujHFtxuClx/Mz2ZocuKoDQaP+m+EmUk 7VDAdOzx+xdpwVroAN5FNTlB X-IronPort-AV: E=Sophos;i="5.84,272,1620716400"; d="scan'208";a="123560057" Received: from smtpout.microchip.com (HELO email.microchip.com) ([198.175.253.82]) by esa4.microchip.iphmx.com with ESMTP/TLS/AES256-SHA256; 26 Jul 2021 21:55:27 -0700 Received: from chn-vm-ex02.mchp-main.com (10.10.87.72) by chn-vm-ex02.mchp-main.com (10.10.87.72) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256) id 15.1.2176.2; Mon, 26 Jul 2021 21:55:27 -0700 Received: from ROB-ULT-M18064N.mchp-main.com (10.10.115.15) by chn-vm-ex02.mchp-main.com (10.10.85.144) with Microsoft SMTP Server id 15.1.2176.2 via Frontend Transport; Mon, 26 Jul 2021 21:55:22 -0700 From: Tudor Ambarus To: , , Subject: [PATCH v2 35/35] docs: mtd: spi-nor: Add details about how to propose a new flash addition Date: Tue, 27 Jul 2021 07:52:22 +0300 Message-ID: <20210727045222.905056-36-tudor.ambarus@microchip.com> X-Mailer: git-send-email 2.25.1 In-Reply-To: <20210727045222.905056-1-tudor.ambarus@microchip.com> References: <20210727045222.905056-1-tudor.ambarus@microchip.com> MIME-Version: 1.0 X-CRM114-Version: 20100106-BlameMichelson ( TRE 0.8.0 (BSD) ) MR-646709E3 X-CRM114-CacheID: sfid-20210726_215529_322250_EE34DE22 X-CRM114-Status: GOOD ( 27.02 ) X-BeenThere: linux-arm-kernel@lists.infradead.org X-Mailman-Version: 2.1.34 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: macromorgan@hotmail.com, jaimeliao@mxic.com.tw, Tudor Ambarus , richard@nod.at, esben@geanix.com, linux@rasmusvillemoes.dk, knaerzche@gmail.com, linux-mtd@lists.infradead.org, linux-arm-kernel@lists.infradead.org, code@reto-schneider.ch, miquel.raynal@bootlin.com, heiko.thiery@gmail.com, sr@denx.de, figgyc@figgyc.uk, mail@david-bauer.net, zhengxunli@mxic.com.tw Sender: "linux-arm-kernel" Errors-To: linux-arm-kernel-bounces+linux-arm-kernel=archiver.kernel.org@lists.infradead.org Add some guideliness on how to propose a new flash addition. Signed-off-by: Tudor Ambarus --- Documentation/driver-api/mtd/spi-nor.rst | 65 ++++++++++++++++++++++++ 1 file changed, 65 insertions(+) diff --git a/Documentation/driver-api/mtd/spi-nor.rst b/Documentation/driver-api/mtd/spi-nor.rst index 4a3adca417fd..ffb8d97a2766 100644 --- a/Documentation/driver-api/mtd/spi-nor.rst +++ b/Documentation/driver-api/mtd/spi-nor.rst @@ -66,3 +66,68 @@ when you want to write a new driver for a SPI NOR controller. Another API is spi_nor_restore(), this is used to restore the status of SPI flash chip such as addressing mode. Call it whenever detach the driver from device or reboot the system. + +Part IV - How to propose a new flash addition? +---------------------------------------------- + +First we have to clarify where the new flash_info entry will reside. Typically +each manufacturer have their own driver and the new flash will be placed in that +specific manufacturer driver. There are cases however, where special care has to +be taken. In case of flash ID collisions between different manufacturers, the +place to add the new flash is in the manuf-id-collisions.c driver. ID collisions +between flashes of the same manufacturer should be handled in their own +manufacturer driver, macronix being an example. There will be a single +flash_info entry for all the ID collisions of the same ID. + +manuf-id-collisions.c is the place to add new flash additions where the +manufacturer is ignorant enough to not implement the ID continuation scheme +that is described in the JEP106 JEDEC Standard. One has to dump its flash ID and +compare it with the flash's manufacturer identification code that is defined in +the JEP106 JEDEC Standard. If the manufacturer ID is defined in bank two or +higher and the manufacturer does not implement the ID continuation scheme, then +it is likely that the flash ID will collide with a manufacturer from bank one or +with other manufacturer from other bank that does not implement the ID +continuation scheme as well. + +flash_info entries will be added in a first come, first served manner. If there +are ID collisions, differentiation between flashes will be done at runtime if +possible. Where runtime differentiation is not possible, new compatibles will be +introduced, but this will be done as a last resort. + +New flash additions that support the SFDP standard should be declared using +SPI_NOR_PARSE_SFDP. Support that can be discovered when parsing SFDP should not +be duplicated by explicit flags at flash declaration. All the SFDP flash +parameters and settings will be discovered when parsing SFDP. There are +flash_info flags that indicate support that is not SFDP discoverable. These +flags initialize non SFDP support in the spi_nor_nonsfdp_flags_init() method. +SPI_NOR_PARSE_SFDP is usually followed by other flash_info flags from the +aforementioned function. Sometimes manufacturers wrongly define some fields in +the SFDP tables. If that's the case, SFDP data can be amended with the fixups() +hooks. It is not common, but if the SFDP tables are entirely wrong, and it does +not worth the hassle to tweak the SFDP parameters by using the fixups hooks, or +if the flash does not define the SFDP tables at all, then one can statically +init the flash with the SPI_NOR_SKIP_SFDP flag and specify the rest of the flash +capabilities with the flash info flags. + +With time we want to convert all flashes to either use SPI_NOR_PARSE_SFDP or +SPI_NOR_SKIP_SFDP and stop triggering the SFDP parsing with the +SPI_NOR_{DUAL, QUAD, OCTAL*}_READ flags. There are flashes that support QUAD +mode but do not support the RDSFDP command, we should avoid issuing unsupported +commands to flashes where possible. It is unlikely that RDSFDP will cause any +problems, but still, it's better to avoid it. There are cases however of flash +ID collisions between flashes that define the SFDP tables and flashes that don't +(again, macronix). We usually differentiate between the two by issuing the +RDSFDP command. In such a case one has to declare the SPI_NOR_PARSE_SFDP +together with all the relevant flags from spi_nor_nonsfdp_flags_init() for the +SFDP compatible flash, but should also declare the relevant flags that are used +in the spi_nor_info_init_params() method in order to init support that can't be +discovered via SFDP for the non-SFDP compatible flash. + +Every new flash addition that define the SFDP tables, should hexdump its SFDP +tables in the patch's comment section below the --- line, so that we can +reference it in case of ID collisions. + +Every flash_info flag declared should be tested. Typically one uses the +mtd-utils and does an erase, verify erase, write, read back and compare test. +Locking and other flags that are declared in the flash_info entry and used in +the spi_nor_nonsfdp_flags_init() should be tested as well.