From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received-SPF: Pass (sender SPF authorized) identity=mailfrom; client-ip=104.47.1.48; helo=eur01-ve1-obe.outbound.protection.outlook.com; envelope-from=pankaj.bansal@nxp.com; receiver=edk2-devel@lists.01.org Received: from EUR01-VE1-obe.outbound.protection.outlook.com (mail-ve1eur01on0048.outbound.protection.outlook.com [104.47.1.48]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-SHA384 (256/256 bits)) (No client certificate requested) by ml01.01.org (Postfix) with ESMTPS id C8F23223DB782 for ; Fri, 9 Feb 2018 03:49:26 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=nxp.com; s=selector1; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version; bh=dD3R+q82HHY1xEzDfLoD77lO9WblmQZysOw7Md+ahE0=; b=vlp7fkSFPvaRD8m7ruHTgM+PhAz28KfeWwnSg1a8qvZr6ZXx0XUdaKQ7xGImvDDrvY+NcWP+hqG+QTL8N1w2961qWmlyZMbi16KF70P/OIvyXnoPsfPpz9my+sITdYS0fFVlvbrVEC6+Enjlc7LIWATPratqMK/IghrwXY/xuBY= Authentication-Results: spf=none (sender IP is ) smtp.mailfrom=pankaj.bansal@nxp.com; Received: from uefi-workstation.ap.freescale.net (192.88.169.1) by VI1PR0402MB3951.eurprd04.prod.outlook.com (2603:10a6:803:23::23) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384_P256) id 15.20.464.11; Fri, 9 Feb 2018 11:55:07 +0000 From: Pankaj Bansal To: edk2-devel@lists.01.org Cc: Pankaj Bansal , Ard Biesheuvel , Leif Lindholm , Michael D Kinney Date: Fri, 9 Feb 2018 17:23:55 +0530 Message-Id: <1518177236-30343-1-git-send-email-pankaj.bansal@nxp.com> X-Mailer: git-send-email 2.7.4 MIME-Version: 1.0 X-Originating-IP: [192.88.169.1] X-ClientProxiedBy: BMXPR01CA0004.INDPRD01.PROD.OUTLOOK.COM (2603:1096:b00:d::14) To VI1PR0402MB3951.eurprd04.prod.outlook.com (2603:10a6:803:23::23) X-MS-PublicTrafficType: Email X-MS-Office365-Filtering-HT: Tenant X-MS-Office365-Filtering-Correlation-Id: ec7c28c6-730e-4c36-4b43-08d56fb3f770 X-Microsoft-Antispam: UriScan:; BCL:0; PCL:0; RULEID:(7020095)(4652020)(4534165)(4627221)(201703031133081)(201702281549075)(48565401081)(5600026)(4604075)(2017052603307)(7153060)(7193020); SRVR:VI1PR0402MB3951; X-Microsoft-Exchange-Diagnostics: 1; VI1PR0402MB3951; 3:hbFzB69sKc+0MJcdqfHLSQB8VfPOjPW1Ekzu8jCyWLuqHTEPIaWOmRhDRk6tHaRdNNSqHv7l+swp89XH08HODkOMZKPZTIaFwObJoBN6QWBplpsnCCbiuqHLAU11IkTm5GlnXIi17G/m+8pJrj9+MwQIHEUDgAq1hD2WNBx2+D45qhcfZSZNpTz/Ad+33sOqv+bxGJ8xveGJRDHF9IqJ4g2ADzmRAv5FJHpDcewJHRw5mpcmR9K79bRmdTb+0YXO; 25:KUo5eOmMvHqv1H9qoXkDvRcm/3mko71zk9+hwHuqLR5Ql5GARnVOIJ3M+k6mCYsN74mHXwQQm4zATgSvtE75e8N1slU1yWB+a/ABcelUCn2qGzWOM9idZK3Q01PZSpGJ+mQVyaUhAfooLQHRKFO53MWO0zuI+Qjuo0MLGTTwSrws/Uu/O00akgKJLXyzHJi7d0GfI6QS3UkvMy46lYnwYkC6aow1gN8HkfKkiYG5EWfII9tSWPF6fjhuCQL7Es7NSesJBhEAniPFsDEdooWU2/wCOeyI6hqD0zP05D+RTxDJKI/vFKIzQ4q+TEBJs465/NHpp2oISGkAcFGyEAA84Q==; 31:2dY3zCiLWUKFXmLzCJ0yQVZ0/PHItPP5CbC4AROc5MnMdnCIGyuriVSvfhxd5lsdlNY9Og5VZU99Ss7kZxYfzBv++taIO3AqkRJ70x6Yiu/DKchfBYXiG6Tci7xgvlWGEea7/2up6T4Nj1ynYMwA3bmH7D+X33LcobmNAOrcsDc3ZZ12u6E5bhVzaqqOgkR767/5h7OSanOYoXWoSvyvFt2nbjPPL0wv3XPbaei8rIc= X-MS-TrafficTypeDiagnostic: VI1PR0402MB3951: X-Microsoft-Exchange-Diagnostics: 1; VI1PR0402MB3951; 20:ZyLF4PcSRBpSnB86U7+rUiM1HgyD6nRNhqJFlhhhBlOtXrBgH+GVbY5lFoMVw3WvQYJuwSMYDDeMUx8cDhIMl9NXNFfrR8A6xEeH3kOd4kX1RK8cs61Qhy31Nz0+kLvN/BeQMtC2lBciumowMS+0649OC+2n6X3wQlTziUWZZ50BFzIdZqt8HEuN9OJG3lU44GJ6MU9CeFQ3DzyRSlZAaDXu2ImXI9R1rYlBeGp7YVXPsdIDLYXWph/12YZorh42+V31bfY1p/KPeM27gRRZIFf4VWmOsZocoX7McPaLZGFBnxYaKf3sdRNaaye537jZx884tPWM24JfDgGxErFhPF4gyzppFoTbBO6PywntXrPbN0OmSbhh4mkEN+KiO6HrBOZ/aFJrlRE3Fo4l/rBcxcK4i6oCTyrfo1zBzD6Lqws1UMb5y2MnW8TRB7Y+RB4BIQpOUGbV5j8tr4vwK2Ry4PvCFx6o5Lry3EWjv1aTRosBQ7UDhEz7DKN5S263d/3T X-Microsoft-Antispam-PRVS: X-Exchange-Antispam-Report-Test: UriScan:(192374486261705)(131327999870524)(185117386973197)(788757137089)(228905959029699); X-Exchange-Antispam-Report-CFA-Test: BCL:0; PCL:0; RULEID:(6040501)(2401047)(5005006)(8121501046)(3002001)(3231101)(2400082)(944501161)(10201501046)(93006095)(93001095)(6055026)(6041288)(20161123562045)(20161123564045)(20161123560045)(20161123558120)(201703131423095)(201702281528075)(20161123555045)(201703061421075)(201703061406153)(6072148)(201708071742011); SRVR:VI1PR0402MB3951; BCL:0; PCL:0; RULEID:; SRVR:VI1PR0402MB3951; X-Microsoft-Exchange-Diagnostics: 1; VI1PR0402MB3951; 4:AIs/H9gvUHUiv9mGV6xF/JCHOz7q72SJ5TVPi/+YU70ikPdRfkbVWkxeIeXvfSRxWiXHwJkg2mYzzfeitc/klQ+9YAjQXsNVbd55WwYESMGLWibgro3HJ5Ydd4STIau2C9rzk7wEmw+tBm/6DUTDbAERGGGERWw8quY5XcR3u/8bb38LmmfZ1z/at7mgSCRxV6Nbl5UwWeXw2fXS8/xzbWCyRxcPgJRYB1PIWWgLmNLYZFIrSAh40rfXbXNg7cC377tfFvu6gso5Mpf3zG7XaRwvdKwrIt6GNOftdASLOWoPRb7P7S6/S4NB6MdXlmcaDb0qpoy3lZ9XV+MHvblEoeqSSDT3xwKcuIhYXVf2TYmMJTU/ZYpuv8TlGQ35lue9jYpT90VmMBTqndNOEWMDOhIhZ0oG2h9tudo7+Eyjv1Lh5r1nyzX2BiwvDNQj43JH X-Forefront-PRVS: 057859F9C5 X-Forefront-Antispam-Report: SFV:NSPM; SFS:(10009020)(366004)(346002)(39860400002)(396003)(376002)(39380400002)(199004)(189003)(47776003)(6666003)(53936002)(5660300001)(6916009)(6512007)(53946003)(6306002)(16586007)(6486002)(16526019)(54906003)(186003)(86362001)(36756003)(316002)(2906002)(26005)(105586002)(50226002)(8936002)(305945005)(81156014)(81166006)(8676002)(25786009)(7736002)(4326008)(48376002)(16799955002)(50466002)(15188155005)(2351001)(51416003)(386003)(59450400001)(106356001)(2361001)(52116002)(97736004)(478600001)(966005)(66066001)(6506007)(68736007)(6116002)(3846002)(551934003)(53376002)(5890100001)(579004); DIR:OUT; SFP:1101; SCL:1; SRVR:VI1PR0402MB3951; H:uefi-workstation.ap.freescale.net; FPR:; SPF:None; PTR:InfoNoRecords; A:1; MX:1; LANG:en; Received-SPF: None (protection.outlook.com: nxp.com does not designate permitted sender hosts) X-Microsoft-Exchange-Diagnostics: =?us-ascii?Q?1; VI1PR0402MB3951; 23:r5MGjE10WbWBD1XhrqJWlIwftOjkMs8Ty3qdYjy?= =?us-ascii?Q?098yhlLC4v/aCDkLYp9PKJtfVn80O48/bj0rG5zpEo4C8CxFXShFTwc7TZH3?= =?us-ascii?Q?FeetFgQCQJth55zAuqwLXSCrQLo++H4OIypQj8zq+02NRnQbWf5C4zDpOXwT?= =?us-ascii?Q?InnX+4GFQQULMsgy1hrJavvtbl8Ebj8Mkzp16yb5s7Uo8AkNMiH3693SgD9p?= =?us-ascii?Q?Bsbh/FkCGlT7dB2DyIpvOMfPUfN+UaLfTpP83laW/E+NzNX6LR7d8GTpIE9n?= =?us-ascii?Q?gkYkC3AUIeIiNm5eiRnHoKA4+xIaBb1Axyb+QqdE1pt4ZJHPEidoIOt6ofAF?= =?us-ascii?Q?nP/6k3CpFbsVOHg3VxF6v3L7G6WbUfUWIyBIvISC+4JmKYJEvv/n+OHDqNqu?= =?us-ascii?Q?egMkHub8KaSC1q5ggCq+N7m5II5rpfQyzkUCD4Y1Nl9CXM6SIrIYP966JV0j?= =?us-ascii?Q?2UQULc6S4Z0rnIUUQcy6i6c83VSTAmH7PBCpmy0IKtPCytMQfpVQBO7GegOZ?= =?us-ascii?Q?K+lxm0FYyZpOX+2nmSoPe+Ag6Md2YpPyHA1zr8ejNXwJkrjUwg/S/yJ2jMmk?= =?us-ascii?Q?9T0VwezR+Ixhbhb0BBKxJqg4pn3nfmZq1JcJofb7c6LB5ZMwElFl/bSbEg2F?= =?us-ascii?Q?J/i+Mjq3SD1blnP1rbZq2LWHR/HHqTKLIhUYFUeLxf9gfQj27bdmKsZvkot/?= =?us-ascii?Q?SrIbyT4uSIxxPR/YcVtS9KpKxMEhY89VCxc0xIRWMJqlASDDO0lXeZNXiKMp?= =?us-ascii?Q?gzTu3bPM/SpZSjR0ohPPoBBw6DxHBr+ohmT8PlwPLhDmyhg7h9UxjUKOpflD?= =?us-ascii?Q?C+13FJUbeQLhcYivEL7JbYbkYFA6d3Nv5RI20qRugJEs60+IpdDw0Hwsz4Z9?= =?us-ascii?Q?E3eHpv4rSoZPcgvSzlYHtDsq8p5aeWnRsktp5cHNf3j92uj5/3SmNvMB+1d+?= =?us-ascii?Q?MDmoc9r4daMoPMmcC+ZGCb37SPBu/jceF1/VGY6e0kbzMeWBq2hwMoP2isce?= =?us-ascii?Q?read/tLd3lcPkEH2HHP2EIEptxkjc09vVLMr+gWh5hSbosEobi/Mrr2PzYXw?= =?us-ascii?Q?1YczrNMjNjoQLO0UtNJK1MkKyBrHwtFfgSkPZAH7EQlg4yUWXGApJL+fAIU2?= =?us-ascii?Q?Tg+b2C17PMUtOBAx3qWoG/g8+bqkDPdGO2xnnUyFvztEOwMe6j0X4ygz/7c3?= =?us-ascii?Q?CWOHSE86S+oEeoNKhf+OFwhomcV1bUYHXsA4CYfDeTitdnxzDMAMt/TRAxpO?= =?us-ascii?Q?q0FCGQIULieIGoWWZ1xKeJ3k3A3ztvR3H3eCJ8hvBJrgvrYvkeQ/do0YEIzv?= =?us-ascii?Q?H8foQE0/n1uPS2mTkgkVhNpAXUlkqOwfAzzfpCBS/zhgk?= X-Microsoft-Exchange-Diagnostics: 1; VI1PR0402MB3951; 6:r0BXfeffbpelC+5wI9quu/12pSnrwojXDfM/Q2vkgAimzEX7MTqY8a6ZByitureEQKCyu1G6hMatSC245bjGtcPpMI6dR9mgeUG6xCZecr8Pmjow+KbPhbzLX6edA1FM5YddnXBUE2iiJc9ZpiJiCo6gPmQWyFF5YAh6Fb82a/5j1TM1e4FaM4RDHZfTPzCc5vHlD1KPUreP1FMFMiH7cRCSXkI/BTCmcWBPn2Oh6UqZ4CRPidk08BlpfN1rjA8HTAWuRf9x7mOX8kI9QhaQtssnyeCFf7zu9lXE8q3tw3n0qZuGTmuL54XH99XCmnOzL9XaSNxL9l7NcmHFnrXQqkA1eRoCmClrSsnigZWjEDk=; 5:EkSdlw7WheCB1yKrHA3M0pE0TQdV7GeCkG6I+y1tjCd27zaSsCemzd4O4qRFu6gKwx66LuWukEt9dJvZIpF1Vkyb9UUUo0Q58oiIdm+rVbJ+R4t2phWdcXJFWj8bSok8EobVUVaEprh199iZLzfeGrvL/k6AnJ9OHL8fLFgEJAs=; 24:kgrJS6KjsdCZZpVEdmDV8SPb4mBPjPiq7OMkHMpLeu0PxSg6jHeZC9wVc5LAjgQsA1toiiKnk8Figq5Pd+BO4Ubx2G5blohNxGErT9UcVdY=; 7:hlkGe3ucDL1xsW/tN9eigKMDx9/WVQ5S8edfBgR1aIslm3nvC1pVfn9t7G9GM0qSBLHKEOEklg0cHZYXn06851waGnBYJe86o7xEdYl9XgrTlXHSDzGz+cOL3nZJbGt9r5FuqCepSGulKNPeTbCWLAb+gUkhSSooVVy+dsCVZjFNO32mODWzKRW4+CjbVmgnyFiIUaE+jYOKa070IR6XIiwhIl+pJfi0cPaP+hJTkNydGFY1j1bklqrnWGlEenYD SpamDiagnosticOutput: 1:99 SpamDiagnosticMetadata: NSPM X-OriginatorOrg: nxp.com X-MS-Exchange-CrossTenant-OriginalArrivalTime: 09 Feb 2018 11:55:07.3641 (UTC) X-MS-Exchange-CrossTenant-Network-Message-Id: ec7c28c6-730e-4c36-4b43-08d56fb3f770 X-MS-Exchange-CrossTenant-FromEntityHeader: Hosted X-MS-Exchange-CrossTenant-Id: 686ea1d3-bc2b-4c6f-a92c-d99c5c301635 X-MS-Exchange-Transport-CrossTenantHeadersStamped: VI1PR0402MB3951 Subject: [PATCH 1/2] Silicon/NXP: Add Modified SPI protocol stack X-BeenThere: edk2-devel@lists.01.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: EDK II Development List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Fri, 09 Feb 2018 11:49:28 -0000 Content-Type: text/plain The PI 1.6 SPI specs are not adequate to handle all type of SPI communication, specially the QUAD mode read/write comminications with the periphrals that support it. Therefore we are modifying the SPI protocol defined in PI 1.6 spec. Untill these changes are incorporated in PI specs, we are calling it revised PI 1.6 spec. Cc: Ard Biesheuvel Cc: Leif Lindholm Cc: Michael D Kinney Contributed-under: TianoCore Contribution Agreement 1.1 Signed-off-by: Pankaj Bansal --- Silicon/NXP/Include/Pi/PiSpi.h | 233 ++++++++++++ .../NXP/Include/Protocol/SpiConfiguration.h | 313 +++++++++++++++++ Silicon/NXP/Include/Protocol/SpiHc.h | 208 +++++++++++ Silicon/NXP/Include/Protocol/SpiIo.h | 168 +++++++++ Silicon/NXP/Include/Protocol/SpiNorFlash.h | 269 ++++++++++++++ 5 files changed, 1191 insertions(+) diff --git a/Silicon/NXP/Include/Pi/PiSpi.h b/Silicon/NXP/Include/Pi/PiSpi.h new file mode 100644 index 0000000..8c35d86 --- /dev/null +++ b/Silicon/NXP/Include/Pi/PiSpi.h @@ -0,0 +1,233 @@ +/** @file + Include file matches things in PI. + + Copyright (c) 2017, Intel Corporation. All rights reserved.
+ Copyright 2017-2018 NXP + + This program and the accompanying materials + are licensed and made available under the terms and conditions of the BSD + License which accompanies this distribution. The full text of the license may + be found at http://opensource.org/licenses/bsd-license.php + + THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, + WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + + @par Revision Reference: + This Protocol was introduced in revised UEFI PI Specification 1.6. + +**/ + +#ifndef __PI_SPI_H__ +#define __PI_SPI_H__ + +/// +/// Define the SPI flags +/// + +/// The SPI peripheral/controller supports only half duplex transactions +#define SPI_HALF_DUPLEX BIT0 +/// The SPI peripheral/controller supports write only transactions. +#define SPI_SUPPORTS_WRITE_ONLY_OPERATIONS BIT1 +/// The SPI peripheral/controller supports Read only transactions. +#define SPI_SUPPORTS_READ_ONLY_OPERATIONS BIT2 +/// The SPI peripheral/controller supports Double Transfer Rate (DTR). +/// DTR : Transfer may be input or output on both the +/// rising and falling edges of the clock. +#define SPI_SUPPORTS_DTR_OPERATIONS BIT3 +/// The SPI peripheral/controller supports a 2-bit data bus +#define SPI_SUPPORTS_2_BIT_DATA_BUS_WIDTH BIT4 +/// The SPI peripheral/controller supports a 4-bit data bus +#define SPI_SUPPORTS_4_BIT_DATA_BUS_WIDTH BIT5 +/// The SPI peripheral/controller supports a 8-bit data bus +#define SPI_SUPPORTS_8_BIT_DATA_BUS_WIDTH BIT6 +/// Transfer size includes the opcode byte +#define SPI_TRANSFER_SIZE_INCLUDES_OPCODE BIT7 +/// Transfer size includes the 4 address bytes +#define SPI_TRANSFER_SIZE_INCLUDES_ADDRESS BIT8 + +/// +/// SPI Frame Size supported Mask +/// +#define SPI_FRAME_MASK(FrameSize) (1U << FrameSize) + +/// +/// Calculate the Clock cycles from number of bytes and BusWidth +/// +#define SPI_BYTES_TO_CYCLES(Bytes, BusWidth) ( ( (Bytes << sizeof (UINT8)) + BusWidth - 1) / BusWidth) +/// +/// Calculate the number of bytes from Clock cycles and BusWidth +/// +#define SPI_CYCLES_TO_BYTES(Cycles, BusWidth) ( (Cycles * BusWidth) >> sizeof (UINT8)) + +/// +/// SPI Device Path can be used to describe the device path of both SPI controller +/// and SPI Peripheral. +/// +typedef struct { + /// + /// Vendor device path specifying Vendor GUID for SPI Host controller or SPI Peripheral. + /// + VENDOR_DEVICE_PATH Vendor; + /// + /// Controller device path to distinguish between two instances of SPI controller or SPI Peripheral. + /// + CONTROLLER_DEVICE_PATH Controller; + /// + /// Signify the end of Device Path. + /// + EFI_DEVICE_PATH_PROTOCOL End; +} EFI_SPI_DEVICE_PATH; + +/// +/// Note: The revised UEFI PI 1.6 specification does not specify values for the +/// members below. The order matches the specification. +/// +typedef enum { + /// + /// Data flowing from the host to the SPI peripheral + /// or Data flowing from the SPI peripheral to the host + /// + SPI_TRANSACTION_DATA = 0, + + /// + /// Command to send to SPI Peripheral + /// + SPI_TRANSACTION_COMMAND, + + /// + /// Offset in SPI Peripheral from/to which data is to be read/written + /// + SPI_TRANSACTION_ADDRESS, + + /// + /// Optional control bits that follow the address bits. + /// These bits are driven by the controller if they are specified. + /// + /// NOTE This field should be counted in clocks not number of bits received by the + /// serial flash. The SPI master drives the bus during "mode bits" cycles; + /// Example: If 8 mode bits are needed with a quad input address phase command, then + /// length for this type of transaction would be 2. + /// + SPI_TRANSACTION_MODE, + + /// + /// Clock cycles during which no data is transferred to or from a memory. + /// the master tri-states the bus during "dummy" cycles. + /// No data (WriteBuffer = NULL and ReadBuffer = NULL) can be specified + /// in SPI Transaction. if these buffer are specified, then SPI HOST controller must ignore + /// these buffers. + /// + SPI_TRANSACTION_DUMMY, + + /// + /// Maximum element that should be present in any enum. + /// + SPI_TRANSACTION_MAX + +} EFI_SPI_TRANSACTION_TYPE; + +/// +/// SPI Peripheral transaction bus width +/// +/// The SPI_TRANSFER_LINE describes the number of data lines to use for +/// a transaction. +/// +typedef enum { + /// One line transfer + SPI_TRANSACTION_BUS_WIDTH_1 = 1, + + /// Two line transfer + SPI_TRANSACTION_BUS_WIDTH_2 = 2, + + /// Four line transfer + SPI_TRANSACTION_BUS_WIDTH_4 = 4, + + /// Eight line transfer + SPI_TRANSACTION_BUS_WIDTH_8 = 8, + + /// Maximum element that should be present in any enum. + SPI_TRANSACTION_BUS_WIDTH +} EFI_SPI_TRANSACTION_BUS_WIDTH; + +/// +/// The EFI_SPI_BUS_TRANSACTION data structure contains the description of the +/// SPI transaction to perform on the host controller. +/// +typedef struct _EFI_SPI_BUS_TRANSACTION { + /// + /// Type of transaction specified by one of the EFI_SPI_TRANSACTION_TYPE + /// values. + /// + EFI_SPI_TRANSACTION_TYPE TransactionType; + + /// + /// TRUE if the transaction is being debugged. Debugging may be turned on for + /// a single SPI transaction. Only this transaction will display debugging + /// messages. All other transactions with this value set to FALSE will not + /// display any debugging messages. + /// + BOOLEAN DebugTransaction; + + /// + /// SPI bus width in bits: 1, 2, 4, 8 + /// + UINT32 BusWidth; + + /// + /// Transfer may be input or output on both the + /// rising and falling edges of the clock. + /// + BOOLEAN DoubleTransferRate; + + /// + /// Frame size in bits, range: 1 - 32 + /// + UINT32 FrameSize; + + /// For TransactionType command/address/data, number of bytes needed to complete the + /// transaction. (Read or write or both). + /// e.g. for 3 byte address the Length is 3. + /// + /// For TransactionType dummy/mode, the clock cycles needed to complete the + /// transaction. + /// e.g. if 1 byte (8 bits) of mode is to be transferred on 2 data bus. + /// then clock cycles needed are 8/2 = 4. so Length is 4. + /// + UINT32 Length; + + /// + /// Buffer containing data to send to the SPI peripheral + /// Frame sizes 1 - 8 bits: UINT8 (one byte) per frame + /// Frame sizes 7 - 16 bits : UINT16 (two bytes) per frame + /// Can be NULL if the SPI TransactionType is SPI_TRANSACTION_DUMMY. + /// + UINT8 *WriteBuffer; + + /// + /// Buffer to receive the data from the SPI peripheral + /// * Frame sizes 1 - 8 bits: UINT8 (one byte) per frame + /// * Frame sizes 7 - 16 bits : UINT16 (two bytes) per frame + /// * Frame sizes 17 - 32 bits : UINT32 (four bytes) per frame + /// Can be NULL if the SPI TransactionType is SPI_TRANSACTION_DUMMY + /// + UINT8 *ReadBuffer; +} EFI_SPI_BUS_TRANSACTION; + +/// +/// SPI device request +/// +/// The EFI_SPI_REQUEST_PACKET describes a single SPI transaction. +/// +typedef struct { + /// + /// Number of elements in the Transaction array + /// + UINTN TransactionCount; + + /// + /// Description of the SPI TransactionTransaction + /// + EFI_SPI_BUS_TRANSACTION Transaction [1]; +} EFI_SPI_REQUEST_PACKET; + +#endif // __PI_SPI_H__ diff --git a/Silicon/NXP/Include/Protocol/SpiConfiguration.h b/Silicon/NXP/Include/Protocol/SpiConfiguration.h new file mode 100644 index 0000000..6383151 --- /dev/null +++ b/Silicon/NXP/Include/Protocol/SpiConfiguration.h @@ -0,0 +1,313 @@ +/** @file + This file defines the SPI Configuration Protocol. + + Copyright (c) 2017, Intel Corporation. All rights reserved.
+ Copyright 2017-2018 NXP + + This program and the accompanying materials + are licensed and made available under the terms and conditions of the BSD + License which accompanies this distribution. The full text of the license may + be found at http://opensource.org/licenses/bsd-license.php + + THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, + WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + + @par Revision Reference: + This Protocol was introduced in UEFI PI Specification 1.6. + +**/ + +#ifndef __SPI_CONFIGURATION_PROTOCOL_H__ +#define __SPI_CONFIGURATION_PROTOCOL_H__ + +/// +/// Global ID for the SPI Configuration Protocol +/// +#define EFI_SPI_CONFIGURATION_GUID \ + { 0x85a6d3e6, 0xb65b, 0x4afc, \ + { 0xb3, 0x8f, 0xc6, 0xd5, 0x4a, 0xf6, 0xdd, 0xc8 }} + +/// +/// Macros to easily specify frequencies in hertz, kilohertz and megahertz. +/// +#define Hz(Frequency) (Frequency) +#define KHz(Frequency) (1000 * Hz (Frequency)) +#define MHz(Frequency) (1000 * KHz (Frequency)) + +typedef struct _EFI_SPI_PERIPHERAL EFI_SPI_PERIPHERAL; + +/** + Manipulate the chip select for a SPI device. + + This routine must be called at or below TPL_NOTIFY. + Update the value of the chip select line for a SPI peripheral. + The SPI bus layer calls this routine either in the board layer or in the SPI + controller to manipulate the chip select pin at the start and end of a SPI + transaction. + + @param[in] SpiPeripheral The address of an EFI_SPI_PERIPHERAL data structure + describing the SPI peripheral whose chip select pin + is to be manipulated. The routine may access the + ChipSelectParameter field to gain sufficient + context to complete the operation. + @param[in] PinValue The value to be applied to the chip select line of + the SPI peripheral. + + @retval EFI_SUCCESS The chip select was set successfully + @retval EFI_NOT_READY Support for the chip select is not properly + initialized + @retval EFI_INVALID_PARAMETER The SpiPeripheral->ChipSelectParameter value + is invalid + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_SPI_CHIP_SELECT) ( + IN CONST EFI_SPI_PERIPHERAL *SpiPeripheral, + IN BOOLEAN PinValue + ); + +/** + Set up the clock generator to produce the correct clock frequency, phase and + polarity for a SPI chip. + + This routine must be called at or below TPL_NOTIFY. + This routine updates the clock generator to generate the correct frequency + and polarity for the SPI clock. + + @param[in] SpiPeripheral Pointer to a EFI_SPI_PERIPHERAL data structure from + which the routine can access the ClockParameter, + ClockPhase and ClockPolarity fields. The routine + also has access to the names for the SPI bus and + chip which can be used during debugging. + @param[in] ClockHz Pointer to the requested clock frequency. The clock + generator will choose a supported clock frequency + which is less then or equal to this value. + Specify zero to turn the clock generator off. + The actual clock frequency supported by the clock + generator will be returned. + + @retval EFI_SUCCESS The clock was set up successfully + @retval EFI_UNSUPPORTED The SPI controller was not able to support the + frequency requested by CLockHz + +**/ +typedef EFI_STATUS +(EFIAPI *EFI_SPI_CLOCK) ( + IN CONST EFI_SPI_PERIPHERAL *SpiPeripheral, + IN UINT32 *ClockHz + ); + +/// +/// The EFI_SPI_PART data structure provides a description of a SPI part which +/// is independent of the use on the board. This data is available directly +/// from the part's datasheet and may be provided by the vendor. +/// +typedef struct _EFI_SPI_PART { + /// + /// A Unicode string specifying the SPI chip vendor. + /// + CONST CHAR16 *Vendor; + + /// + /// A Unicode string specifying the SPI chip part number. + /// + CONST CHAR16 *PartNumber; + + /// + /// The minimum SPI bus clock frequency used to access this chip. This value + /// may be specified in the chip's datasheet. If not, use the value of zero. + /// + UINT32 MinClockHz; + + /// + /// The maximum SPI bus clock frequency used to access this chip. This value + /// is found in the chip's datasheet. + /// + UINT32 MaxClockHz; + + /// + /// Specify the polarity of the chip select pin. This value can be found in + /// the SPI chip's datasheet. Specify TRUE when a one asserts the chip select + ///and FALSE when a zero asserts the chip select. + /// + BOOLEAN ChipSelectPolarity; +} EFI_SPI_PART; + +/// +/// The EFI_SPI_BUS data structure provides the connection details between the +/// physical SPI bus and the EFI_SPI_HC_PROTOCOL instance which controls that +/// SPI bus. This data structure also describes the details of how the clock is +/// generated for that SPI bus. Finally this data structure provides the list +/// of physical SPI devices which are attached to the SPI bus. +/// +typedef struct _EFI_SPI_BUS { + /// + /// A Unicode string describing the SPI bus + /// + CONST CHAR16 *FriendlyName; + + /// + /// Address of the first EFI_SPI_PERIPHERAL data structure connected to this + /// bus. Specify NULL if there are no SPI peripherals connected to this bus. + /// + CONST EFI_SPI_PERIPHERAL *Peripherallist; + + /// + /// Address of the first Runtime EFI_SPI_PERIPHERAL data structure connected to this + /// bus. Specify NULL if there are no Runtime SPI peripherals connected to this bus. + /// + CONST EFI_SPI_PERIPHERAL *RuntimePeripherallist; + + /// + /// Address of an EFI_DEVICE_PATH_PROTOCOL data structure which uniquely + /// describes the SPI controller. + /// + CONST EFI_DEVICE_PATH_PROTOCOL *ControllerPath; + + /// + /// Address of the routine which controls the clock used by the SPI bus for + /// this SPI peripheral. The SPI host controller's clock routine is called + /// when this value is set to NULL. + /// + EFI_SPI_CLOCK Clock; + + /// + /// Address of a data structure containing the additional values which + /// describe the necessary control for the clock. When Clock is NULL, + /// the declaration for this data structure is provided by the vendor of the + /// host's SPI controller driver. When Clock is not NULL, the declaration for + /// this data structure is provided by the board layer. + /// + VOID *ClockParameter; +} EFI_SPI_BUS; + +/// +/// The EFI_SPI_PERIPHERAL data structure describes how a specific block of +/// logic which is connected to the SPI bus. This data structure also selects +/// which upper level driver is used to manipulate this SPI device. +/// The SpiPeripheraLDriverGuid is available from the vendor of the SPI +/// peripheral driver. +/// +struct _EFI_SPI_PERIPHERAL { + /// + /// Address of the next EFI_SPI_PERIPHERAL data structure. Specify NULL if + /// the current data structure is the last one on the SPI bus. + /// + CONST EFI_SPI_PERIPHERAL *NextSpiPeripheral; + + /// + /// A unicode string describing the function of the SPI part. + /// + CONST CHAR16 *FriendlyName; + + /// + /// Address of a GUID provided by the vendor of the SPI peripheral driver. + /// Instead of using a " EFI_SPI_IO_PROTOCOL" GUID, the SPI bus driver uses + /// this GUID to identify an EFI_SPI_IO_PROTOCOL data structure and to + /// provide the connection points for the SPI peripheral drivers. + /// This reduces the comparison logic in the SPI peripheral driver's + /// Supported routine. + /// + CONST GUID *SpiPeripheralDriverGuid; + + /// + /// The address of an EFI_SPI_PART data structure which describes this chip. + /// + CONST EFI_SPI_PART *SpiPart; + + /// + /// The maximum clock frequency is specified in the EFI_SPI_P ART. When this + /// this value is non-zero and less than the value in the EFI_SPI_PART then + /// this value is used for the maximum clock frequency for the SPI part. + /// + UINT32 MaxClockHz; + + /// + /// Specify the idle value of the clock as found in the datasheet. + /// Use zero (0) if the clock'S idle value is low or one (1) if the the + /// clock's idle value is high. + /// + BOOLEAN ClockPolarity; + + /// + /// Specify the clock delay after chip select. Specify zero (0) to delay an + /// entire clock cycle or one (1) to delay only half a clock cycle. + /// + BOOLEAN ClockPhase; + + /// + /// SPI peripheral attributes, select zero or more of: + /// * SPI_HALF_DUPLEX - The SPI peripheral supports only half duplex + /// transactions + /// * SPI_SUPPORTS_WRITE_ONLY_OPERATIONS - The SPI peripheral supports + /// write only transactions. + /// * SPI_SUPPORTS_READ_ONLY_OPERATIONS - The SPI peripheral supports + /// read only transactions. + /// * SPI_SUPPORTS_DTR_OPERATIONS - The SPI peripheral supports + /// Double Transfer Rate (DTR). + /// DTR : Transfer may be input or output on both the + /// rising and falling edges of the clock. + /// * SPI_SUPPORTS_2_B1T_DATA_BUS_W1DTH - The SPI peripheral is wired to + /// support a 2-bit data bus + /// * SPI_SUPPORTS_4_B1T_DATA_BUS_W1DTH - The SPI peripheral is wired to + /// support a 4-bit data bus + /// * SPI_SUPPORTS_8_B1T_DATA_BUS_W1DTH - The SPI peripheral is wired to + /// support a 8-bit data bus + /// + UINT32 Attributes; + + /// + /// Address of a vendor specific data structure containing additional board + /// configuration details related to the SPI chip. The SPI peripheral layer + /// uses this data structure when configuring the chip. + /// + CONST VOID *ConfigurationData; + + /// + /// The address of an EFI_SPI_BUS data structure which describes the SPI bus + /// to which this chip is connected. + /// + CONST EFI_SPI_BUS *SpiBus; + + /// + /// Address of the routine which controls the chip select pin for this SPI + /// peripheral. Call the SPI host controller's chip select routine when this + /// value is set to NULL. + /// + EFI_SPI_CHIP_SELECT ChipSelect; + + /// + /// Address of a data structure containing the additional values which + /// describe the necessary control for the chip select. When ChipSelect is + /// NULL, the declaration for this data structure is provided by the vendor + /// of the host's SPI controller driver. The vendor's documentation specifies + /// the necessary values to use for the chip select pin selection and + /// control. When Chipselect is not NULL, the declaration for this data + /// structure is provided by the board layer. + /// + VOID *ChipSelectParameter; +}; + +/// +/// Describe the details of the board's SPI busses to the SPI driver stack. +/// The board layer uses the EFI_SPI_CONFIGURATION_PROTOCOL to expose the data +/// tables which describe the board's SPI busses, The SPI bus layer uses these +/// tables to configure the clock, chip select and manage the SPI transactions +/// on the SPI controllers. +/// +typedef struct _EFI_SPI_CONFIGURATION_PROTOCOL { + /// + /// The number of SPI busses on the board. + /// + UINT32 BusCount; + + /// + /// The address of an array of EFI_SPI_BUS data structure addresses. + /// + CONST EFI_SPI_BUS *CONST *CONST Buslist; +} EFI_SPI_CONFIGURATION_PROTOCOL; + +extern EFI_GUID gEfiSpiConfigurationProtocolGuid; + +#endif // __SPI_CONFIGURATION_PROTOCOL_H__ diff --git a/Silicon/NXP/Include/Protocol/SpiHc.h b/Silicon/NXP/Include/Protocol/SpiHc.h new file mode 100644 index 0000000..86d27b3 --- /dev/null +++ b/Silicon/NXP/Include/Protocol/SpiHc.h @@ -0,0 +1,208 @@ +/** @file + This file defines the SPI Host Controller Protocol. + + Copyright (c) 2017, Intel Corporation. All rights reserved.
+ Copyright 2017-2018 NXP + + This program and the accompanying materials + are licensed and made available under the terms and conditions of the BSD + License which accompanies this distribution. The full text of the license may + be found at http://opensource.org/licenses/bsd-license.php + + THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, + WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + + @par Revision Reference: + This Protocol was introduced in revised UEFI PI Specification 1.6. + +**/ + +#ifndef __SPI_HC_PROTOCOL_H__ +#define __SPI_HC_PROTOCOL_H__ + +#include +#include + +/// +/// Global ID for the SPI Host Controller Protocol +/// +#define EFI_SPI_HOST_GUID \ + { 0xc74e5db2, 0xfa96, 0x4ae2, \ + { 0xb3, 0x99, 0x15, 0x97, 0x7f, 0xe3, 0x0, 0x2d }} + +/// +/// EDK2-style name +/// +#define EFI_SPI_HC_PROTOCOL_GUID EFI_SPI_HOST_GUID + +typedef struct _EFI_SPI_HC_PROTOCOL EFI_SPI_HC_PROTOCOL; + +/** + Assert or deassert the SPI chip select. + + This routine is called at TPL_NOTIFY. + Update the value of the chip select line for a SPI peripheral. The SPI bus + layer calls this routine either in the board layer or in the SPI controller + to manipulate the chip select pin at the start and end of a SPI transaction. + + @param[in] This Pointer to an EFI_SPI_HC_PROTOCOL structure. + @param[in] SpiPeripheral The address of an EFI_SPI_PERIPHERAL data structure + describing the SPI peripheral whose chip select pin + is to be manipulated. The routine may access the + ChipSelectParameter field to gain sufficient + context to complete the operation. + @param[in] PinValue The value to be applied to the chip select line of + the SPI peripheral. + + @retval EFI_SUCCESS The chip select was set as requested + @retval EFI_NOT_READY Support for the chip select is not properly + initialized + @retval EFI_INVALID_PARAMETER The ChipSeLect value or its contents are + invalid + +**/ +typedef EFI_STATUS +(EFIAPI *EFI_SPI_HC_PROTOCOL_CHIP_SELECT) ( + IN CONST EFI_SPI_HC_PROTOCOL *This, + IN CONST EFI_SPI_PERIPHERAL *SpiPeripheral, + IN BOOLEAN PinValue + ); + +/** + Set up the clock generator to produce the correct clock frequency, phase and + polarity for a SPI chip. + + This routine is called at TPL_NOTIFY. + This routine updates the clock generator to generate the correct frequency + and polarity for the SPI clock. + + @param[in] This Pointer to an EFI_SPI_HC_PROTOCOL structure. + @param[in] SpiPeripheral Pointer to a EFI_SPI_PERIPHERAL data structure from + which the routine can access the ClockParameter, + ClockPhase and ClockPolarity fields. The routine + also has access to the names for the SPI bus and + chip which can be used during debugging. + @param[in] ClockHz Pointer to the requested clock frequency. The SPI + host controller will choose a supported clock + frequency which is less then or equal to this + value. Specify zero to turn the clock generator + off. The actual clock frequency supported by the + SPI host controller will be returned. + + @retval EFI_SUCCESS The clock was set up successfully + @retval EFI_UNSUPPORTED The SPI controller was not able to support the + frequency requested by ClockHz + +**/ +typedef EFI_STATUS +(EFIAPI *EFI_SPI_HC_PROTOCOL_CLOCK) ( + IN CONST EFI_SPI_HC_PROTOCOL *This, + IN CONST EFI_SPI_PERIPHERAL *SpiPeripheral, + IN UINT32 *ClockHz + ); + +/** + Perform the SPI transaction on the SPI peripheral using the SPI host + controller. + + This routine is called at TPL_NOTIFY. + This routine synchronously returns EFI_SUCCESS indicating that the + asynchronous SPI transaction was started. The routine then waits for + completion of the SPI transaction prior to returning the final transaction + status. + + @param[in] This Pointer to an EFI_SPI_HC_PROTOCOL structure. + @param[in] RequestPacket Pointer to a EFI_SPI_REQUEST_PACKET containing + the description of the SPI transactions to perform. + + @retval EFI_SUCCESS The transaction completed successfully. + @retval EFI_ALREADY_STARTED The controller is busy with another transaction. + @retval EFI_BAD_BUFFER_SIZE The Length value in SPI Transaction is wrong. + @retval EFI_DEVICE_ERROR There was an SPI error during the transaction. + @retval EFI_INVALID_PARAMETER The parameters specified in RequestPacket are not + Valid. or the RequestPacket is NULL. + @retval EFI_NO_RESPONSE The SPI device is not responding to the slave + address. EFI_DEVICE_ERROR will be returned if + the controller cannot distinguish when the NACK + occurred. + @retval EFI_UNSUPPORTED The controller does not support the requested + transaction. +**/ +typedef EFI_STATUS +(EFIAPI *EFI_SPI_HC_PROTOCOL_TRANSACTION) ( + IN CONST EFI_SPI_HC_PROTOCOL *This, + IN EFI_SPI_REQUEST_PACKET *RequestPacket + ); + +/// +/// Support a SPI data transaction between the SPI controller and a SPI chip. +/// +struct _EFI_SPI_HC_PROTOCOL { + /// + /// Host control attributes, may have zero or more of the following set: + /// * SPI_HALF_DUPLEX - The SPI Host Controller supports only half duplex + /// transactions + /// * SPI_SUPPORTS_WRITE_ONLY_OPERATIONS - The SPI Host Controller supports + /// write only transactions. + /// * SPI_SUPPORTS_READ_ONLY_OPERATIONS - The SPI Host Controller supports + /// read only transactions. + /// * SPI_SUPPORTS_DTR_OPERATIONS - The SPI Host Controller supports + /// Double Transfer Rate (DTR). + /// DTR : Transfer may be input or output on both the + /// rising and falling edges of the clock. + /// * SPI_SUPPORTS_2_B1T_DATA_BUS_W1DTH - The SPI Host Controller is wired to + /// support a 2-bit data bus + /// * SPI_SUPPORTS_4_B1T_DATA_BUS_W1DTH - The SPI Host Controller is wired to + /// support a 4-bit data bus + /// * SPI_SUPPORTS_8_B1T_DATA_BUS_W1DTH - The SPI Host Controller is wired to + /// support a 8-bit data bus + /// The SPI host controller must support a 1 - bit bus + /// width. + /// * HC_TX_FRAME_IN_MOST_SIGNIFICANT_BITS + /// - The SPI host controller requires the transmit frame to be in most + /// significant bits instead of least significant bits.The host driver + /// will adjust the frames if necessary. + /// * HC_RX_FRAME_IN_MOST_SIGNIFICANT_BITS + /// - The SPI host controller places the receive frame to be in most + /// significant bits instead of least significant bits.The host driver + /// will adjust the frames to be in the least significant bits if + /// necessary. + /// * SPI_TRANSFER_SIZE_INCLUDES_OPCODE + /// - Transfer size includes the opcode byte + /// * SPI_TRANSFER_SIZE_INCLUDES_ADDRESS + /// - Transfer size includes the 4 address bytes + UINT32 Attributes; + + /// + /// Mask of frame sizes which the SPI host controller supports. Frame size of + /// N-bits is supported when bit N-1 is set. The host controller must support + /// a frame size of 8-bits. + /// + UINT32 FrameSizeSupportMask; + + /// + /// Maximum transfer size in bytes: 1 - Oxffffffff + /// + UINT32 MaximumTransferBytes; + + /// + /// Assert or deassert the SPI chip select. + /// + EFI_SPI_HC_PROTOCOL_CHIP_SELECT ChipSelect; + + /// + /// Set up the clock generator to produce the correct clock frequency, phase + /// and polarity for a SPI chip. + /// + EFI_SPI_HC_PROTOCOL_CLOCK Clock; + + /// + /// Perform the SPI transaction on the SPI peripheral using the SPI host + /// controller. + /// + EFI_SPI_HC_PROTOCOL_TRANSACTION Transaction; +}; + +extern EFI_GUID gEfiSpiHcProtocolGuid; + +#endif // __SPI_HC_PROTOCOL_H__ diff --git a/Silicon/NXP/Include/Protocol/SpiIo.h b/Silicon/NXP/Include/Protocol/SpiIo.h new file mode 100644 index 0000000..c08c3bd --- /dev/null +++ b/Silicon/NXP/Include/Protocol/SpiIo.h @@ -0,0 +1,168 @@ +/** @file + This file defines the SPI I/O Protocol. + + Copyright (c) 2017, Intel Corporation. All rights reserved.
+ Copyright 2017-2018 NXP + + This program and the accompanying materials + are licensed and made available under the terms and conditions of the BSD + License which accompanies this distribution. The full text of the license may + be found at http://opensource.org/licenses/bsd-license.php + + THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, + WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + + @par Revision Reference: + This Protocol was introduced in revised UEFI PI Specification 1.6. + +**/ + +#ifndef __SPI_IO_PROTOCOL_H__ +#define __SPI_IO_PROTOCOL_H__ + +#include +#include +#include + +typedef struct _EFI_SPI_IO_PROTOCOL EFI_SPI_IO_PROTOCOL; + +/** + Initiate a SPI transaction between the host and a SPI peripheral. + + This routine must be called at or below TPL_NOTIFY. + This routine works with the SPI bus layer to pass the SPI transactions to the + SPI controller for execution on the SPI bus. + + @param[in] This Pointer to an EFI_SPI_IO_PROTOCOL structure. + @param[in] RequestPacket Pointer to an EFI_SPI_REQUEST_PACKET + structure describing the SPI transactions. + + @param[in] ClockHz Specify the ClockHz value as zero (0) to use + the maximum clock frequency supported by the + SPI controller and part. Specify a non-zero + value only when a specific SPI transaction + requires a reduced clock rate. + + @retval EFI_SUCCESS The transaction completed successfully. + @retval EFI_ALREADY_STARTED The controller is busy with another transaction. + @retval EFI_BAD_BUFFER_SIZE The Length value in SPI Transaction is wrong. + @retval EFI_DEVICE_ERROR There was an SPI error during the transaction. + @retval EFI_INVALID_PARAMETER The parameters specified in RequestPacket are not + Valid. or the RequestPacket is NULL. + @retval EFI_NOT_READY Support for the chip select is not properly + initialized + @retval EFI_INVALID_PARAMETER The ChipSeLect value or its contents are + invalid + @retval EFI_NO_RESPONSE The SPI device is not responding to the slave + address. EFI_DEVICE_ERROR will be returned if + the controller cannot distinguish when the NACK + occurred. + @retval EFI_UNSUPPORTED The controller does not support the requested + transaction. or The SPI controller was not able to support + the frequency requested by ClockHz +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_SPI_IO_PROTOCOL_TRANSACTION) ( + IN CONST EFI_SPI_IO_PROTOCOL *This, + IN EFI_SPI_REQUEST_PACKET *RequestPacket, + IN UINT32 ClockHz OPTIONAL + ); + +/** + Update the SPI peripheral associated with this SPI 10 instance. + + Support socketed SPI parts by allowing the SPI peripheral driver to replace + the SPI peripheral after the connection is made. An example use is socketed + SPI NOR flash parts, where the size and parameters change depending upon + device is in the socket. + + @param[in] This Pointer to an EFI_SPI_IO_PROTOCOL structure. + @param[in] SpiPeripheral Pointer to an EFI_SPI_PERIPHERAL structure. + + @retval EFI_SUCCESS The SPI peripheral was updated successfully + @retval EFI_INVALID_PARAMETER The SpiPeripheral value is NULL, + or the SpiPeripheral->SpiBus is NULL, + or the SpiP eripheral - >SpiBus pointing at + wrong bus, + or the SpiP eripheral - >SpiPart is NULL + +**/ +typedef EFI_STATUS +(EFIAPI *EFI_SPI_IO_PROTOCOL_UPDATE_SPI_PERIPHERAL) ( + IN CONST EFI_SPI_IO_PROTOCOL *This, + IN CONST EFI_SPI_PERIPHERAL *SpiPeripheral + ); + +/// +/// Support managed SPI data transactions between the SPI controller and a SPI +/// chip. +/// +struct _EFI_SPI_IO_PROTOCOL { + /// + /// Address of an EFI_SPI_PERIPHERAL data structure associated with this + /// protocol instance. + /// + CONST EFI_SPI_PERIPHERAL *SpiPeripheral; + + /// + /// Address of the original EFI_SPI_PERIPHERAL data structure associated with + /// this protocol instance. + /// + CONST EFI_SPI_PERIPHERAL *OriginalSpiPeripheral; + + /// + /// Mask of frame sizes which the SPI 10 layer supports. Frame size of N-bits + /// is supported when bit N-1 is set. The host controller must support a + /// frame size of 8-bits. Frame sizes of 16, 24 and 32-bits are converted to + /// 8-bit frame sizes by the SPI bus layer if the frame size is not supported + /// by the SPI host controller. + /// + UINT32 FrameSizeSupportMask; + + /// + /// Maximum transfer size in bytes: 1 - Oxffffffff + /// + UINT32 MaximumTransferBytes; + + /// + /// Transaction attributes: One or more from: + /// * SPI_HALF_DUPLEX + /// - The SPI host or peripheral supports only half duplex transactions + /// * SPI_SUPPORTS_WRITE_ONLY_OPERATIONS + /// - The SPI host or peripheral supports write only transactions. + /// * SPI_SUPPORTS_READ_ONLY_OPERATIONS + /// - The SPI host or peripheral support read only transactions. + /// * SPI_SUPPORTS_DTR_OPERATIONS + /// - The SPI SPI host and peripheral supports Double Transfer Rate (DTR). + /// DTR : Transfer may be input or output on both the + /// rising and falling edges of the clock. + /// * SPI_SUPPORTS_2_B1T_DATA_BUS_W1DTH + /// - The SPI host and peripheral supports a 2-bit data bus + /// * SPI_SUPPORTS_4_BIT_DATA_BUS_W1DTH + /// - The SPI host and peripheral supports a 4-bit data bus + /// * SPI_SUPPORTS_8_BIT_DATA_BUS_W1DTH + /// - The SPI host and peripheral supports a 8-bit data bus + /// * SPI_TRANSFER_SIZE_INCLUDES_OPCODE + /// - Transfer size includes the opcode byte + /// * SPI_TRANSFER_SIZE_INCLUDES_ADDRESS + /// - Transfer size includes the 4 address bytes + UINT32 Attributes; + + /// + /// Pointer to legacy SPI controller protocol + /// + CONST EFI_LEGACY_SPI_CONTROLLER_PROTOCOL *LegacySpiProtocol; + + /// + /// Initiate a SPI transaction between the host and a SPI peripheral. + /// + EFI_SPI_IO_PROTOCOL_TRANSACTION Transaction; + + /// + /// Update the SPI peripheral associated with this SPI 10 instance. + /// + EFI_SPI_IO_PROTOCOL_UPDATE_SPI_PERIPHERAL UpdateSpiPeripheral; +}; + +#endif // __SPI_IO_PROTOCOL_H__ diff --git a/Silicon/NXP/Include/Protocol/SpiNorFlash.h b/Silicon/NXP/Include/Protocol/SpiNorFlash.h new file mode 100644 index 0000000..2e57107 --- /dev/null +++ b/Silicon/NXP/Include/Protocol/SpiNorFlash.h @@ -0,0 +1,269 @@ +/** @file + This file defines the SPI NOR Flash Protocol. + + Copyright (c) 2017, Intel Corporation. All rights reserved.
+ Copyright 2018 NXP + + This program and the accompanying materials + are licensed and made available under the terms and conditions of the BSD + License which accompanies this distribution. The full text of the license may + be found at http://opensource.org/licenses/bsd-license.php + + THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, + WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + + @par Revision Reference: + This Protocol was introduced in revised UEFI PI Specification 1.6. + +**/ + +#ifndef __SPI_NOR_FLASH_PROTOCOL_H__ +#define __SPI_NOR_FLASH_PROTOCOL_H__ + +#include + +/// +/// Global ID for the SPI NOR Flash Protocol +/// +#define EFI_SPI_NOR_FLASH_PROTOCOL_GUID \ + { 0xb57ec3fe, 0xf833, 0x4ba6, \ + { 0x85, 0x78, 0x2a, 0x7d, 0x6a, 0x87, 0x44, 0x4b }} + +typedef struct _EFI_SPI_NOR_FLASH_PROTOCOL EFI_SPI_NOR_FLASH_PROTOCOL; + +/** + Read the 3 byte manufacture and device ID from the SPI flash. + + This routine must be called at or below TPL_NOTIFY. + This routine reads the 3 byte manufacture and device ID from the flash part + filling the buffer provided. + + @param[in] This Pointer to an EFI_SPI_NOR_FLASH_PROTOCOL data structure. + @param[out] Buffer Pointer to a 3 byte buffer to receive the manufacture and + device ID. + + + + @retval EFI_SUCCESS The manufacture and device ID was read + successfully. + @retval EFI_INVALID_PARAMETER Buffer is NULL + @retval EFI_DEVICE_ERROR Invalid data received from SPI flash part. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_SPI_NOR_FLASH_PROTOCOL_GET_FLASH_ID) ( + IN CONST EFI_SPI_NOR_FLASH_PROTOCOL *This, + OUT UINT8 *Buffer + ); + +/** + Read data from the SPI flash. + + This routine must be called at or below TPL_NOTIFY. + This routine reads data from the SPI part in the buffer provided. + + @param[in] This Pointer to an EFI_SPI_NOR_FLASH_PROTOCOL data + structure. + @param[in] FlashAddress Address in the flash to start reading + @param[in] LengthInBytes Read length in bytes + @param[out] Buffer Address of a buffer to receive the data + + @retval EFI_SUCCESS The data was read successfully. + @retval EFI_INVALID_PARAMETER Buffer is NULL, or + FlashAddress >= This->FlashSize, or + LengthInBytes > This->FlashSize - FlashAddress + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_SPI_NOR_FLASH_PROTOCOL_READ_DATA) ( + IN CONST EFI_SPI_NOR_FLASH_PROTOCOL *This, + IN UINT32 FlashAddress, + IN UINT32 LengthInBytes, + OUT UINT8 *Buffer + ); + +/** + Read the flash status register. + + This routine must be called at or below TPL_NOTIFY. + This routine reads the flash part status register. + + @param[in] This Pointer to an EFI_SPI_NOR_FLASH_PROTOCOL data + structure. + @param[in] LengthInBytes Number of status bytes to read. + @param[out] FlashStatus Pointer to a buffer to receive the flash status. + + @retval EFI_SUCCESS The status register was read successfully. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_SPI_NOR_FLASH_PROTOCOL_READ_STATUS) ( + IN CONST EFI_SPI_NOR_FLASH_PROTOCOL *This, + IN UINT32 LengthInBytes, + OUT UINT8 *FlashStatus + ); + +/** + Write the flash status register. + + This routine must be called at or below TPL_N OTIFY. + This routine writes the flash part status register. + + @param[in] This Pointer to an EFI_SPI_NOR_FLASH_PROTOCOL data + structure. + @param[in] LengthInBytes Number of status bytes to write. + @param[in] FlashStatus Pointer to a buffer containing the new status. + + @retval EFI_SUCCESS The status write was successful. + @retval EFI_OUT_OF_RESOURCES Failed to allocate the write buffer. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_SPI_NOR_FLASH_PROTOCOL_WRITE_STATUS) ( + IN CONST EFI_SPI_NOR_FLASH_PROTOCOL *This, + IN UINT32 LengthInBytes, + IN UINT8 *FlashStatus + ); + +/** + Write data to the SPI flash. + + This routine must be called at or below TPL_NOTIFY. + This routine breaks up the write operation as necessary to write the data to + the SPI part. + + @param[in] This Pointer to an EFI_SPI_NOR_FLASH_PROTOCOL data + structure. + @param[in] FlashAddress Address in the flash to start writing + @param[in] LengthInBytes Write length in bytes + @param[in] Buffer Address of a buffer containing the data + + @retval EFI_SUCCESS The data was written successfully. + @retval EFI_INVALID_PARAMETER Buffer is NULL, or + FlashAddress >= This->FlashSize, or + LengthInBytes > This->FlashSize - FlashAddress + @retval EFI_OUT_OF_RESOURCES Insufficient memory to copy buffer. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_SPI_NOR_FLASH_PROTOCOL_WRITE_DATA) ( + IN CONST EFI_SPI_NOR_FLASH_PROTOCOL *This, + IN UINT32 FlashAddress, + IN UINT32 LengthInBytes, + IN UINT8 *Buffer + ); + +/** + Efficiently erases one or more 4KiB regions in the SPI flash. + + This routine must be called at or below TPL_NOTIFY. + This routine uses a combination of 4 KiB and larger blocks to erase the + specified area. + + @param[in] This Pointer to an EFI_SPI_NOR_FLASH_PROTOCOL data + structure. + @param[in] FlashAddress Address within a 4 KiB block to start erasing + @param[in] BlockCount Number of 4 KiB blocks to erase + + @retval EFI_SUCCESS The erase was completed successfully. + @retval EFI_INVALID_PARAMETER FlashAddress >= This->FlashSize, or + BlockCount * 4 KiB + > This->FlashSize - FlashAddress + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_SPI_NOR_FLASH_PROTOCOL_ERASE) ( + IN CONST EFI_SPI_NOR_FLASH_PROTOCOL *This, + IN UINT32 FlashAddress, + IN UINT32 BlockCount + ); + +/// +/// The EFI_SPI_NOR_FLASH_PROTOCOL exists in the SPI peripheral layer. +/// This protocol manipulates the SPI NOR flash parts using a common set of +/// commands. The board layer provides the interconnection and configuration +/// details for the SPI NOR flash part. The SPI NOR flash driver uses this +/// configuration data to expose a generic interface which provides the +/// following APls: +/// * Read manufacture and device ID +/// * Read data +/// * Read data using low frequency +/// * Read status +/// * Write data +/// * Erase 4 KiB blocks +/// * Erase 32 or 64 KiB blocks +/// * Write status +/// The EFI_SPI_NOR_FLASH_PROTOCOL also exposes some APls to set the security +/// features on the legacy SPI flash controller. +/// +struct _EFI_SPI_NOR_FLASH_PROTOCOL { + /// + /// Pointer to an EFI_SPI_PERIPHERAL data structure + /// + CONST EFI_SPI_PERIPHERAL *SpiPeripheral; + + /// + /// Flash size in bytes + /// + UINT32 FlashSize; + + /// + /// Manufacture and Device ID + /// + UINT8 Deviceid[3]; + + /// + /// Erase block size in bytes + /// + UINT32 EraseBlockBytes; + + /// + /// Page Write size in bytes + /// + UINT32 PageWriteSize; + + /// + /// Read the 3 byte manufacture and device ID from the SPI flash. + /// + EFI_SPI_NOR_FLASH_PROTOCOL_GET_FLASH_ID GetFlashid; + + /// + /// Read data from the SPI flash. + /// + EFI_SPI_NOR_FLASH_PROTOCOL_READ_DATA ReadData; + + /// + /// Low frequency read data from the SPI flash. + /// + EFI_SPI_NOR_FLASH_PROTOCOL_READ_DATA LfReadData; + + /// + /// Read the flash status register. + /// + EFI_SPI_NOR_FLASH_PROTOCOL_READ_STATUS ReadStatus; + + /// + /// Write the flash status register. + /// + EFI_SPI_NOR_FLASH_PROTOCOL_WRITE_STATUS WriteStatus; + + /// + /// Write data to the SPI flash. + /// + EFI_SPI_NOR_FLASH_PROTOCOL_WRITE_DATA WriteData; + + /// + /// Efficiently erases one or more 4KiB regions in the SPI flash. + /// + EFI_SPI_NOR_FLASH_PROTOCOL_ERASE Erase; +}; + +extern EFI_GUID gEfiSpiNorFlashProtocolGuid; + +#endif // __SPI_NOR_FLASH_PROTOCOL_H__ -- 2.7.4