{"id":13649306,"url":"https://github.com/ZipCPU/sdspi","last_synced_at":"2025-04-22T14:31:18.747Z","repository":{"id":55157909,"uuid":"68862960","full_name":"ZipCPU/sdspi","owner":"ZipCPU","description":"SD-Card controller, using either SPI, SDIO, or eMMC interfaces","archived":false,"fork":false,"pushed_at":"2024-05-22T14:45:12.000Z","size":7450,"stargazers_count":146,"open_issues_count":0,"forks_count":25,"subscribers_count":9,"default_branch":"master","last_synced_at":"2024-05-22T16:03:42.539Z","etag":null,"topics":["axi","emmc","fpga","sd-card","sd-interface","sdio","spi-interface","verilator","verilog","verilog-components","wishbone","wishbone-bus"],"latest_commit_sha":null,"homepage":"","language":"Verilog","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ZipCPU.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-09-21T22:30:37.000Z","updated_at":"2024-06-05T20:11:54.326Z","dependencies_parsed_at":"2022-08-14T13:51:07.007Z","dependency_job_id":"ffe07689-ce26-4d9f-b535-a0c4ff3b8faa","html_url":"https://github.com/ZipCPU/sdspi","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ZipCPU%2Fsdspi","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ZipCPU%2Fsdspi/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ZipCPU%2Fsdspi/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ZipCPU%2Fsdspi/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ZipCPU","download_url":"https://codeload.github.com/ZipCPU/sdspi/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250258930,"owners_count":21401000,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["axi","emmc","fpga","sd-card","sd-interface","sdio","spi-interface","verilator","verilog","verilog-components","wishbone","wishbone-bus"],"created_at":"2024-08-02T01:04:56.224Z","updated_at":"2025-04-22T14:31:13.721Z","avatar_url":"https://github.com/ZipCPU.png","language":"Verilog","readme":"# SD-Card controller\n\nThis repository contains two Verilog hardware RTL controllers for handling\nSD cards from an FPGA.  The [first and older controller](rtl/sdspi.v) handles\nSD cards via their (optional) SPI interface.  The [second and newer\ncontroller](rtl/sdio.v) works using the SDIO interface.  This [second\ncontroller](rtl/sdio.v) has also been demonstrated to handle eMMC cards as well.\n\n## SPI-based controller\n\n[The SDSPI controller](rtl/sdspi.v) exports an SD card controller interface\nfrom internal to an FPGA to the rest of the FPGA core, while taking care of the\nlower level details internal to the interface.  Unlike the [SDIO\ncontroller](rtl/sdio.v) in this respository, this controller focuses on the SPI\ninterface of the SD Card.  While this is a slower interface, the SPI interface\nis necessary to access the card when using a [XuLA2\nboard](http://www.xess.com/shop/product/xula2-lx25/) (for which it was\noriginally written), or in general any time the full 7--bit, bi--directional\ninterface to the SD card has not been implemented.  Further, for those who are\ndie--hard Verilog authors, this core is written in Verilog as opposed to the\n[XESS provided demonstration SD Card controller found on\nGitHub](https://github.com/xesscorp/VHDL\\_Lib/SDCard.vhd), which was written\nin VHDL.  For those who are not such die--hard Verilog authors, this controller\nprovides a lower level interface to the card than other controllers. \nWhereas the [XESS controller](https://github.com/xesscorp/VHDL\\_Lib/SDCard.vhd)\nwill automatically start up the card and interact with it, this controller\nrequires [external software](sw/sdspidrv.c) to be used when interacting with\nthe card.  This makes this SDSPI controller both more versatile, in the face\nof potential changes to the card interface, but also less turn-key.\n\nWhile this core was written for the purpose of being used with the\n[ZipCPU](https://github.com/ZipCPU/zipcpu), as enhanced by the Wishbone DMA\ncontroller used by the ZipCPU, nothing in this core prevents it from being\nused with any other architecture that supports the 32-bit Wishbone interface\nof this core.\n\nThis core has been written as a wishbone slave, not a master.  Using the core\ntogether with a separate master, such as a CPU or a DMA controller, only makes\nsense.  This design choice, however, also restricts the core from being able to\nuse the multiple block write or multiple block read commands, restricting it to \nsingle block read and write commands alone.\n\n### Roadmap and TODO items\n\n*Status*: The SDSPI IP is **silicon proven**.  It is no longer under active\n  development.  It has been used successfully in several FPGA projects.  The\n  components of this IP have formal proofs, which they are known to pass.  A\n  Verilator [C++ model](bench/cpp/sdspisim.cpp) also exists which can fairly\n  faithfully represent an SD card's SPI interface.  A [software\n  library](sw/sdspidrv.c) also exists which can act as a back end when using\n  the [FATFS library](http://elm-chan.org/fsw/ff/00index_e.html).\n\n- **AXI Support**: The [SDSPI controller](doc/sdspi.pdf) has no support for\n  an AXI environment.  The RTL modifications required to provide AXI-Lite\n  support to this controller would be minor.  Testbench modifications would\n  be more significant.\n\n- **All-Verilog Test bench**: The [SDSPI controller](doc/sdspi.pdf) has a\n  [C++ model](bench/cpp/sdspisim.cpp) only for simulation based testing.\n  There is no all Verilog test bench at present, nor do I have any plans to\n  develop one.\n\nFor more information, please consult the [SDSPI user guide](doc/sdspi.pdf).\n\n## SDIO\n\nThis repository also contains a [second and newer SD card\ncontroller](rtl/sdio.v), designed to exploit both the full SDIO protocol and\nthe 8b EMMC protocol--either with or without data strobes.  This controller\nhas been tested against both SDIO and eMMC chips, with the differences between\nthe two types of chips handled by software.\n\nThe interface to this controller is roughly the same as that of the [SDSPI\ncontroller](rtl/sdspi.v), although there are enough significant differences\nto warrant a [separate user guide](doc/sdio.pdf).\n\nThe controller is designed to support IO modes all the way up to the HS400\nmode used by eMMC.  HS400 is an eMMC DDR mode based off of a 200MHz IO clock,\nusing a data strobe pin on return.  Also supported are an SDR mode using a\n200MHz clock, DDR and SDR modes using a 100MHz clock, as well as both DDR and\nSDR support for integer divisions of the 100MHz clock, starting with a 50MHz\nclock and going all the way down to 100kHz.  This is all based upon a nominal\n100MHz system clock, together with a 400MHz clock for SERDES support.  For\ndesigns without 8:1 and 1:8 SERDES IO components, 100MHz and slower clocks are\nstill supported, depending upon whether or not DDR I/O components are available.\nBoth open-drain and push-pull IOs are supported, and the front end can switch\nbetween the two as necessary based upon options within a PHY configuration\nregister.  No support is planned for any of the UHS-II protocols.\n\nBoth Wishbone and AXI-Lite interfaces are supported.\n\n*Status*: The SDIO controller has now been **silicon proven**.  It is currently\n  working successfully in [its first FPGA\n  project](https://github.com/ZipCPU/eth10g), where it is being used to control\n  both an SD card as well as an eMMC chip.  It is also now working successfully\n  in a [second project](https://github.com/ZipCPU/videozip/).  Many of the\n  components of this IP have formal proofs, which they are known to pass.\n\n  Notably missing among the formal component proofs is a proof of the [front\n  end](rtl/sdfrontend.v).  The [front end](rtl/sdfrontend.v)'s verification\n  depends upon integrated simulation testing.\n\n  Both [Verilog](bench/verilog/mdl_sdio.v) and [C++](bench/cpp/sdiosim.cpp)\n  models have been built which can be used to test this controller in\n  simulation.  Unlike the [Verilog SDIO](bench/verilog/mdl_sdio.v) model, the\n  [C++ SDIO](bench/cpp/sdiosim.cpp) supports a file-backed memory, allowing\n  full software testing with filesystem(s) present.  All three simulation\n  components have been now been tested successfully: the Verilog\n  [SDIO](bench/verilog/mdl_sdio.v) and [eMMC](bench/verilog/mdl_emmc.v)\n  models, as well as the [SDIO C++](bench/cpp/sdiosim.cpp) model.\n\nFor more information, please consult the [SDIO user guide](doc/sdio.pdf).\n\n### Roadmap and TODO items\n\nAlthough the initial RTL has both been fully drafted and successfully hardware\ntested, this project is far from finished.  Several key steps remain before\nthis controller will be a completed product:\n\n- **Multi-block**: Multiple block commands have been demonstrated in\n  simulation when using the Verilog [SDIO model](bench/verilog/mdl_sdio.v).\n  Multiblock simulation support is still lacking in the Verilog [eMMC\n  model](bench/verilog/mdl_emmc.v).\n\n  Multiblock commands form the basis for the DMA's operation.\n\n- **`OPT_DMA`**: An optional DMA is now available, and passing tests in silicon.\n\n  Only the Wishbone version of the DMA controller exists at present.\n\n  Although components exist in my [wb2axip\n  repository](https://github.com/ZipCPU/wb2axip) which could support an AXI\n  DMA, these components have neither been integrated nor tested as part of this\n  design.  Other user's have successfully connected external AXI\n  [MM2S](https://github.com/ZipCPU/wb2axip/blob/master/rtl/aximm2s.v) and\n  [S2MM](https://github.com/ZipCPU/wb2axip/blob/master/rtl/axis2mm.v)\n  components to the AXI stream interface, and have thus demonstrated successful\n  DMA support in AXI environments.\n\n- **STREAM DMA**: At customer request, hooks now exist for an (optional)\n  stream DMA interface.  This interface will accept an AXI stream input,\n  and/or an AXI stream output.  Data present on the AXI stream input may\n  then be written directly to the device.  Reads from the device may also\n  produce data at the output stream.\n\n  This interface is now supported and [tested via\n  simulation](bench/testscript/sdstream.v).  No known issues exist.  It does\n  have some software quirks:\n\n  - When using the stream interface, the DMA address should be set to -1.  This\n    selects the stream interface as either source or destination.  (The actual\n    controller command will indicate the direction of the transfer.)\n  - Any memory source ([MM2S](https://github.com/ZipCPU/wb2axip/blob/master/rtl/aximm2s.v))\n    should be configured for the full transfer length--potentially many blocks.\n  - There is no TLAST stream input (slave).\n  - When the external (SD or eMMC) device is the data source ([S2MM](https://github.com/ZipCPU/wb2axip/blob/master/rtl/axis2mm.v)),\n    the TLAST signal will be set at the end of each 512B block.  This may\n    require the external DMA to be configured to transfer data one block at a\n    time, or perhaps to ignore the TLAST signal.\n  - Transfer errors (failing CRCs, non-responsive cards, etc.) may cause the streams to be unsynchronized.  To fix, the design may be given a soft reset (if necessary), and the external [MM2S](https://github.com/ZipCPU/wb2axip/blob/master/rtl/aximm2s.v)/[S2MM](https://github.com/ZipCPU/wb2axip/blob/master/rtl/axis2mm.v) DMAs may also need to be given similar resets.\n\n- **C++ Model**: A [Verilator C++ model of an SDIO\n  component](bench/cpp/sdiosim.cpp) is now a part of the repository.  This\n  model has demonstrated tremendous utility when doing software testing.\n\n  No C++ eMMC model exists at present.\n\n- **SW Testing**: [Control software](sw/) has been written, and has been\n  used to demonstrate both [SDIO](sw/sdiodrv.c) and [EMMC](sw/emmcdrvr.c)\n  performance.  This software is designed to work with the [FATFS\n  library](http://elm-chan.org/fsw/ff/00index_e.html).\n\n  Software testing is currently taking place as part of the integrated test\n  benches associated with separate repositories, such as the\n  [VideoZip](https://github.com/ZipCPU/videozip) repository that contains both\n  this component and the [ZipCPU](https://zipcpu.com/about/zipcpu.html).\n\n- **AXI Support**: This design has also been demonstrated in AXI environments.\n  The control interface has an AXI-Lite port which can be used to interact\n  with the IP.  A flag exists to swap endianness, so that the design will be\n  properly little endian when using this interface.  At present, however,\n  there is no integrated AXI DMA master capability--only AXI stream ports.\n  (Integrated AXI DMA master support is planned, just not funded at present.)\n\n  When coupled with external AXI\n  [MM2S](https://github.com/ZipCPU/wb2axip/blob/master/rtl/aximm2s.v) and\n  [S2MM](https://github.com/ZipCPU/wb2axip/blob/master/rtl/axis2mm.v)\n  components, the IP may sufficiently provide for the needs of most AXI\n  environments.\n\n- **CRC Tokens**: CRC token's are 5b response values, indicating whether\n  or not a page has transferred successfully.\n  The [frontend](rtl/sdfrontend.v) can successfully recognize those CRC tokens\n  following block write transfers.\n\n  Failure to receive a CRC token when one is expected will (now) generate an\n  error condition, as will receiving a negative CRC acknowledgment.\n\n- **eMMC Boot mode**: No plan exists to support eMMC boot mode (at present).\n  This decision will likely be revisited in the future.\n\n  Some (untested, preliminary) support exists for boot mode in the Verilog\n  [eMMC model](bench/verilog/mdl_emmc.v).\n\n- **eMMC Collision Detection**: [Collision detection remains an ongoing issue\n  with eMMC support](https://github.com/ZipCPU/sdspi/issues/13).  This issue\n  is limited to the `GO_IRQ_STATE` command, and specifically to the case where\n  both controller and device attempt to leave the IRQ state at the same time.\n  Without collision support, the message to leave the IRQ state may be\n  corrupted on return.  This should be detectable via a bad CRC on the command\n  line.\n\n# Logic usage\n\nCurrent logic usage is being tracked for iCE40 and Xilinx 6-LUT devices\nin the [usage.txt](rtl/usage.txt) file in the [RTL/](rtl/) directory.\n\n# Commercial Applications\n\nShould you find the GPLv3 license insufficient for your needs, other licenses\nmay be purchased from Gisselquist Technology, LLC.\n","funding_links":[],"categories":["Verilog"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FZipCPU%2Fsdspi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FZipCPU%2Fsdspi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FZipCPU%2Fsdspi/lists"}