Merge branch 'development'

.gitignore

@@ -0,0 +1,8 @@
+# Build directory
+build/
+
+# Cortex-Debug extension debug artifacts
+.vscode/.cortex*
+
+# FatFS documentation
+ff14b/documents

.gitmodules

@@ -0,0 +1,3 @@
+[submodule "littlefs"]
+	path = littlefs
+	url = https://github.com/littlefs-project/littlefs

.vscode/c_cpp_properties.json

@@ -0,0 +1,17 @@
+{
+    "configurations": [
+        {
+            "name": "Linux",
+            "includePath": [
+                "${workspaceFolder}/**"
+            ],
+            "defines": [],
+            "compilerPath": "/bin/arm-none-eabi-gcc",
+            "cStandard": "gnu17",
+            "cppStandard": "gnu++17",
+            "intelliSenseMode": "linux-gcc-arm",
+            "configurationProvider": "ms-vscode.cmake-tools"
+        }
+    ],
+    "version": 4
+}

.vscode/launch.json

@@ -0,0 +1,30 @@
+{
+    "version": "0.2.0",
+    "configurations": [
+        {
+            "name": "PicoMemcard",
+            "device": "RP2040",
+            "gdbPath": "gdb-multiarch",
+            "cwd": "${workspaceRoot}",
+            "executable": "${workspaceRoot}/build/PicoMemcard.elf",
+            "preLaunchTask": "build",
+            "request": "launch",
+            "type": "cortex-debug",
+            "servertype": "openocd",
+            "configFiles": [
+                "interface/picoprobe.cfg",
+                "target/rp2040.cfg"
+            ],
+            "openOCDLaunchCommands": [
+                "transport select swd",
+                "adapter speed 4000"
+            ],
+            "svdFile": "${env:PICO_SDK_PATH}/src/rp2040/hardware_regs/rp2040.svd",
+            "runToEntryPoint": "main",
+            "postRestartCommands": [
+                "break main",
+                "continue"
+            ]
+        }
+    ]
+}

.vscode/settings.json

@@ -0,0 +1,16 @@
+{
+    "files.associations": {
+        "stdio.h": "c",
+        "stdlib.h": "c",
+        "pio.h": "c",
+        "pico.h": "c",
+        "uart.h": "c",
+        "types.h": "c",
+        "tusb.h": "c",
+        "board.h": "c",
+        "tusb_common.h": "c",
+        "tusb_option.h": "c",
+        "ansi_escape.h": "c",
+        "tusb_compiler.h": "c"
+    }
+}

.vscode/tasks.json

@@ -0,0 +1,14 @@
+{
+    "version": "2.0.0",
+    "tasks": [
+        {
+            "label": "build",
+            "type": "shell",
+            "command": "cmake --build ${workspaceRoot}/build --config Debug --target all -j 10",
+            "group": {
+                "kind": "build",
+                "isDefault": true
+            }
+        },
+    ]
+}

CMakeLists.txt

@@ -0,0 +1,43 @@
+cmake_minimum_required(VERSION 3.13)
+
+include(pico_sdk_import.cmake)
+
+project(picomemcard_project C CXX ASM)
+set(CMAKE_C_STANDARD 11)
+set(CMAKE_CXX_STANDARD 17)
+pico_sdk_init()
+
+add_executable(PicoMemcard)
+
+pico_set_linker_script(PicoMemcard ${CMAKE_SOURCE_DIR}/memmap.ld)
+pico_generate_pio_header(PicoMemcard ${CMAKE_CURRENT_LIST_DIR}/psxSPI.pio)
+
+
+# Example source
+target_sources(PicoMemcard PUBLIC
+    ${CMAKE_SOURCE_DIR}/src/lfs_disk.c
+    ${CMAKE_SOURCE_DIR}/src/lfs_flash_handler.c
+    ${CMAKE_SOURCE_DIR}/src/main.c
+    ${CMAKE_SOURCE_DIR}/src/memcard_simulator.c
+    ${CMAKE_SOURCE_DIR}/src/memory_card.c
+    ${CMAKE_SOURCE_DIR}/src/msc_handler.c
+    ${CMAKE_SOURCE_DIR}/src/ram_disk.c
+    ${CMAKE_SOURCE_DIR}/src/usb_descriptors.c
+    ${CMAKE_SOURCE_DIR}/ff14b/source/diskio.c
+    ${CMAKE_SOURCE_DIR}/ff14b/source/ff.c
+    ${CMAKE_SOURCE_DIR}/littlefs/lfs.c
+    ${CMAKE_SOURCE_DIR}/littlefs/lfs_util.c
+)
+
+# Example include
+target_include_directories(PicoMemcard PUBLIC
+    ${CMAKE_SOURCE_DIR}/inc
+    ${CMAKE_SOURCE_DIR}/ff14b/source
+    ${CMAKE_SOURCE_DIR}/littlefs
+)
+
+pico_enable_stdio_uart(PicoMemcard 1)	# enable only UART stdio
+
+target_link_libraries(PicoMemcard pico_stdlib pico_time hardware_flash hardware_pio tinyusb_device tinyusb_board)
+
+pico_add_extra_outputs(PicoMemcard)

README.md

@@ -0,0 +1,90 @@
+# PicoMemcard
+PicoMemcard allows you to build your own supercharged PSX Memory Card that can be connected to your computer via USB in order to transfer saves directly to/from your PSX. Can be used to repurpose broken/counterfit Memory Cards into new ones using only a Raspberry Pi Pico.
+
+## Features
+* Able to simulate faithfully PSX Memory Card
+* USB conection to import/export saves
+* Allows to copy saves to/from any other memory card (using original PSX file manager)
+* Compatible with [FreePSXBoot]
+* Cheaper than a used original memory card.
+
+## Bills of materials
+* **Raspberry Pi Pico** (around ~5$)
+* One of:
+    * Custom PicoMemcard PCB (*currently work in progress*)
+    * Broken/Counterfit/Original PSX Memory Card (counterfit ones can be found on Aliexpress for less than 1$)
+    * PSX/PS2 Controller Cable
+    * Nothing, if you are a mad man and feel like soldering cables directly to your PSX (would not recommend).
+
+Basically anything that will allow you to interface with the memory card slot pins will do. If you have a broken contoller you can cut of the cable and use that since controllers and memory cards share the same bus. Of course, plugging your memory card into the controller slot will prevent you from using 2 controllers at the same time.
+
+In total building a PicoMemcard wil cost you less than buying an used original Memory Card!
+
+## How it works
+[![PicoMemcard Tutorial](https://img.youtube.com/vi/A49-PsrNzP0/0.jpg)](https://www.youtube.com/watch?v=A49-PsrNzP0)
+
+## Wiring
+The wiriting diagram below shows how to wire the Pi Pico and a counterfit memory card from Aliexpress. For the other cases (wiring directly to the PSX or using a controller cable) the pins on the Pico are the same, the pinout of the PSX/controller can be found on [psx-spx]. The image shows the bottom side of the memory card with the cover removed.
+
+<img src="./docs/wiring_bg.svg" alt="Wiring Diagram" width="800">
+
+The dashed line on the PCB of the memory card is where you should cut a groove using a xacto knife deep enough to disconnect the original controller from the traces. The yellow squares above the line indicate where you should scrape away the proctective film in order to expose the traces and solder the wires onto.
+
+Finally the area on the bottom part of the memory card is where I cut a hole to feed the wires through and connect them to the Pico.
+
+## Installation
+1. Download the latest [release].
+2. While bressing the 'BOOTSEL' button on your Raspberry Pi Pico, plug it into your computer. 
+3. Drag and drop the PicoMemcard onto your Raspberry Pi Pico.
+4. PicoMemcard should appear on your PC as a USB drive.
+5. Upload a memory card image to your PicoMemcard.
+
+## Transfering Data
+As of the current release, uploading data to PicoMemcard requires some precises steps:
+* The image of the memory card to upload must be called exactly `MEMCARD.MCR`. Uploading anything else will not result in any errors but PicoMemcard will not save the uploaded data to flash, after rebooting the device the old data will still be present.
+* The image must be 128KB (131072 bytes) in size which is precisely the size of an original Memory Card.
+* After the image has been uploaded, the device **must be safely ejected** in order for the data to be actually imported correctly. This is a limitation of the current implementation (see Design section).
+
+Inside `docs/images` you can find a couple of memory card images. One has a couple of saves on it so you can test if everything works correctly, the other is completely empty.
+
+**ATTENTION:**
+I would recommend to never plug the PicoMemcard both into the PC (via USB) and the PSX at the same time! Otherwise the 5V provided by USB would end up on the 3.3V rail of the PSX. I'm not really sure if this could cause actual damage but I would avoid it.
+
+If you really need to have the Pico plugged into both the USB and PSX (e.g. for debugging purposes), disconnect the 3.3V line from the VBUS pin. In this way you can power on the Pico using a simple USB phone charger or by plugging it into your PC.
+
+## Future Development
+As of now PicoMemcard is still in very early development stages and only tested it on a PSOne Pal model (SCPH-102, bios version 4.4) and may work or not on your PSX. If you want to try it on your PSX any feedback would be much appreciated.
+
+I've tried to make the project as accessible as possible by using the least amount of hardware but this comes with a few limitations, in particular regarding the flash storage of the Pico. In the future I want to add the possibility to use a microSD card by adding a microSD SPI module, this would improve on the following:
+* The very limited storage preventing from having multiple memory card images at the same time and being able to switch them using a button on the Pico.
+* The complex codebase using multiple filesystems (see [Design](#design) section).
+* The brief downtime periods PicoMemcard may have while writing new data to flash memory, appearing as if the Memory Card was briefly disconnected.
+* The need to perform save ejection as a way to signal the Pico to transfer the data from the virtual FAT disk to the flash filesystem (see [Design](#design) section).
+
+## Design
+For people interested in underestanding how PicoMemcard works I provide a more extensive explanation in [this post].
+
+## Thanks To
+* [psx-spx] and Martin "NO$PSX" Korth - Playstation Specifications and documented Memory Card protocol and filesystem.
+* [Andrew J. McCubbin] - Additional information about Memory Card and Controller comunication with PSX.
+* [littlefs] - Filesystem designed to work on NOR flash used by many microcontrollers, including the Raspberry Pi Pico.
+* [ChaN FatFS] - FAT filesystem implementation for embeeded devices.
+* [Scoppy] - Use your Raspberry Pi Pico as an oscilloscope, very cheap and accurate. Without this I would have not been able to debug many issues.
+* [PulseView] - Used to import, visualize and manipulate the data from Scoppy on a PC.
+
+[FreePSXBoot]: https://github.com/brad-lin/FreePSXBoot
+[psx-spx]: https://psx-spx.consoledev.net/pinouts/#controller-ports-and-memory-card-ports
+[Andrew J. McCubbin]: http://www.emudocs.org/PlayStation/psxcont/
+[littlefs]: https://github.com/littlefs-project/littlefs
+[ChaN FatFS]: http://elm-chan.org/fsw/ff/00index_e.html
+[Scoppy]: https://github.com/fhdm-dev/scoppy
+[PulseView]: https://sigrok.org/wiki/PulseView
+[release]: https://TODO_ADD_LINK_TO_RELEASE
+[this post]: https://dangiu.github.io/2022/05/13/picomemcard.html
+
+
+<!-- 
+TODO
+Add FAQ? Is it necessary?
+Add Changelog
+-->

ff14b/LICENSE.txt

@@ -0,0 +1,24 @@
+FatFs License
+
+FatFs has being developped as a personal project of the author, ChaN. It is free from the code anyone else wrote at current release. Following code block shows a copy of the FatFs license document that heading the source files.
+
+/*----------------------------------------------------------------------------/
+/  FatFs - Generic FAT Filesystem Module  Rx.xx                               /
+/-----------------------------------------------------------------------------/
+/
+/ Copyright (C) 20xx, ChaN, all right reserved.
+/
+/ FatFs module is an open source software. Redistribution and use of FatFs in
+/ source and binary forms, with or without modification, are permitted provided
+/ that the following condition is met:
+/
+/ 1. Redistributions of source code must retain the above copyright notice,
+/    this condition and the following disclaimer.
+/
+/ This software is provided by the copyright holder and contributors "AS IS"
+/ and any warranties related to this software are DISCLAIMED.
+/ The copyright owner or contributors be NOT LIABLE for any damages caused
+/ by use of this software.
+/----------------------------------------------------------------------------*/
+
+Therefore FatFs license is one of the BSD-style licenses, but there is a significant feature. FatFs is mainly intended for embedded systems. In order to extend the usability for commercial products, the redistributions of FatFs in binary form, such as embedded code, binary library and any forms without source code, do not need to include about FatFs in the documentations. This is equivalent to the 1-clause BSD license. Of course FatFs is compatible with the most of open source software licenses include GNU GPL. When you redistribute the FatFs source code with changes or create a fork, the license can also be changed to GNU GPL, BSD-style license or any open source software license that not conflict with FatFs license.