Flashing Tang Nano 20k: A Comprehensive Guide

Are you new to the Tang Nano 20k or the MiSTle project and finding the flashing process a bit confusing? You're not alone! This comprehensive guide addresses common questions and provides clear instructions to help you flash your Tang Nano 20k successfully. Let's dive in and get those bits flashing correctly!

Understanding the Flashing Process

When venturing into the world of FPGA development with boards like the Tang Nano 20k, understanding the flashing process is absolutely essential. The flashing process involves writing data, such as the FPGA configuration (bitstream) and other firmware components, to the flash memory of the device. This allows the FPGA to load and execute the desired functionality. For beginners, it can seem daunting, but breaking down the process into manageable steps and understanding the tools involved makes it much easier. The correct approach ensures the stability and proper functioning of the device. This guide aims to provide a clear, step-by-step explanation, making it easier for newcomers to grasp and implement the necessary steps.

Initial Setup and Software

Before starting, ensure you have the necessary software installed. The Gowin Programmer is crucial for flashing the Tang Nano 20k. As the original poster mentioned using Version V1.9.12_SP1 on Windows 11, it's a good starting point. Make sure this version is compatible with your operating system. Once the software is installed, familiarize yourself with its interface, particularly the options for selecting the device, access mode, and operation types. These configurations are vital for successful flashing. Correct software setup from the beginning can prevent many common errors and save considerable time.

Common Challenges and Solutions

Many users encounter issues during flashing, such as error messages or the device not functioning as expected after the flash. A common cause is incorrect settings within the Gowin Programmer, like choosing the wrong access mode or operation. Another pitfall is using incompatible or corrupted files. Double-checking these aspects before initiating the flash process can often resolve such problems. Additionally, ensuring the USB connection is stable and the device is properly recognized by the computer is important. Keeping a log of the steps taken and any error messages can also help in troubleshooting, either independently or when seeking assistance from online communities. Addressing these challenges proactively ensures a smoother and more successful flashing experience.

Addressing Specific Questions

Let's address the specific questions raised to clarify the flashing process for the Tang Nano 20k.

Question 1: Command 38/39 and Data Overwriting

When using commands 38 or 39 ("exFlash Erase, Program, (Verify) thru GAO-Bridge"), it's crucial to understand their behavior concerning existing data in the flash memory. These commands typically erase the sectors of the flash memory where new data will be written. So, if you're flashing the Atari 2600 or Amiga bitstreams using these commands, they will overwrite any existing data in the affected sectors, including any previously flashed 1541 ROMs. The extent of the erasure depends on the size of the data being flashed. If the new data is smaller than the erased sector, the remaining portion of the sector will be left blank. Therefore, it is important to plan and manage memory allocation carefully to avoid unintentionally deleting essential data. Always back up critical data before performing flash operations to prevent data loss.

Question 2: Full Flash Memory Reset

To perform a full reset of the flash memory on your Tang Nano 20k, especially after setting incorrect addresses, you would typically use the exFlash Bulk Erase command. Command 10 (exFlash Bulk Erase) or command 14 (exFlash Bulk Erase in bscan) are both designed for this purpose. Command 10 is usually the standard method. However, command 14, which utilizes Boundary Scan (BSCAN), might be necessary in certain situations, particularly if there are issues with the standard erase process. Before executing a bulk erase, it's critical to ensure that you have backups of any essential data, as this operation will completely wipe the flash memory. Always double-check the command and its implications to avoid accidental data loss.

Question 3: Unplugging and Replugging the TN20k

Yes, after flashing both .fs and .bin files, it is generally necessary to unplug and replug (pressing button S2) the Tang Nano 20k for the changes to take effect. This step ensures that the FPGA reloads the newly flashed configuration from the flash memory. Adding "pause" commands in your 1541 script after each flash command is a good practice because it provides a moment to verify that each flashing step was successful before proceeding to the next. This approach helps prevent potential issues and allows for easier troubleshooting if something goes wrong during the flashing process. The replugging action essentially resets the board and initiates the boot process with the new data.

Best Practices for Flashing

To ensure a smooth and successful flashing experience with your Tang Nano 20k, consider these best practices:

• Verify File Integrity: Always double-check the integrity of the .fs and .bin files before flashing. Corrupted files can lead to unexpected behavior or even brick your device.
• Use Correct Addresses: Pay close attention to the memory addresses when flashing different components. Overlapping addresses can cause conflicts and data corruption.
• Backup Important Data: Before making any changes to the flash memory, create backups of any essential data. This precaution can save you from potential data loss.
• Follow the Correct Sequence: Adhere to the recommended flashing sequence. Flashing components in the wrong order can lead to compatibility issues.
• Monitor the Process: Keep a close watch on the flashing process through the Gowin Programmer. Look for any error messages or warnings and address them promptly.
• Stay Updated: Keep your Gowin Programmer software up to date. Newer versions often include bug fixes and improvements that can enhance the flashing experience.

Creating Batch Files for Efficiency

Creating batch files, as you've done, is an efficient way to automate the flashing process. Here are some tips to enhance your batch files:

• Add Error Handling: Incorporate error handling to detect and report any issues during the flashing process.
• Use Comments: Add comments to explain each command and its purpose. This will make your batch files more readable and maintainable.
• Parameterize Paths: Use variables to store file paths, making it easier to update the script if the file locations change.
• Log Output: Redirect the output of each command to a log file for troubleshooting purposes.

Example of Enhanced Batch File

@echo off

REM Set file paths
set PROGRAMMER_PATH=Programmer\bin\programmer_cli
set FS_FILE="C:\Users\xyz\Desktop\C64Nano\C64Nano_TN20k.fs"
set BIN_FILE_2DOSA="C:\Users\xyz\Desktop\C64Nano\2dosa_c.bin"
set BIN_FILE_DOS1541="C:\Users\xyz\Desktop\C64Nano\dos1541-325302-01+901229-05.bin"
set BIN_FILE_C1541ROM="C:\Users\xyz\Desktop\C64Nano\C1541.ROM"
set BIN_FILE_JIFFYDOS="C:\Users\xyz\Desktop\C64Nano\JiffyDOS_C1541.bin"

REM Flash the .fs file
echo Flashing .fs file...
%PROGRAMMER_PATH% --device GW2AR-18C --operation_index 37 --fsFile %FS_FILE% --spiaddr 0x000000 > flash_fs.log 2>&1
if %errorlevel% neq 0 (
 echo Error flashing .fs file. Check flash_fs.log for details.
 pause
 exit /b
)
echo .fs file flashed successfully.
pause

REM Flash 2dosa_c.bin
echo Flashing 2dosa_c.bin...
%PROGRAMMER_PATH% --device GW2AR-18C --operation_index 39 --mcuFile %BIN_FILE_2DOSA% --spiaddr 0x200000 > flash_2dosa.log 2>&1
if %errorlevel% neq 0 (
 echo Error flashing 2dosa_c.bin. Check flash_2dosa.log for details.
 pause
 exit /b
)
echo 2dosa_c.bin flashed successfully.
pause

REM Flash dos1541-325302-01+901229-05.bin
echo Flashing dos1541-325302-01+901229-05.bin...
%PROGRAMMER_PATH% --device GW2AR-18C --operation_index 39 --mcuFile %BIN_FILE_DOS1541% --spiaddr 0x20C000 > flash_dos1541.log 2>&1
if %errorlevel% neq 0 (
 echo Error flashing dos1541-325302-01+901229-05.bin. Check flash_dos1541.log for details.
 pause
 exit /b
)
echo dos1541-325302-01+901229-05.bin flashed successfully.
pause

REM Flash C1541.ROM
echo Flashing C1541.ROM...
%PROGRAMMER_PATH% --device GW2AR-18C --operation_index 39 --mcuFile %BIN_FILE_C1541ROM% --spiaddr 0x214000 > flash_c1541rom.log 2>&1
if %errorlevel% neq 0 (
 echo Error flashing C1541.ROM. Check flash_c1541rom.log for details.
 pause
 exit /b
)
echo C1541.ROM flashed successfully.
pause

REM Flash JiffyDOS_C1541.bin
echo Flashing JiffyDOS_C1541.bin...
%PROGRAMMER_PATH% --device GW2AR-18C --operation_index 39 --mcuFile %BIN_FILE_JIFFYDOS% --spiaddr 0x21C000 > flash_jiffydos.log 2>&1
if %errorlevel% neq 0 (
 echo Error flashing JiffyDOS_C1541.bin. Check flash_jiffydos.log for details.
 pause
 exit /b
)
echo JiffyDOS_C1541.bin flashed successfully.
pause

echo All flashing operations completed.
pause
exit /b

This enhanced batch file includes error checking, logging, and parameterized paths, making it more robust and easier to use.

Conclusion

Flashing the Tang Nano 20k involves understanding the tools, commands, and best practices. By addressing common questions and providing clear instructions, this guide aims to make the process more accessible for beginners. Remember to verify file integrity, use correct addresses, and create backups before flashing. With these tips and the enhanced batch file example, you'll be well-equipped to flash your Tang Nano 20k successfully.

For further information and troubleshooting, refer to the Gowin official website. Good luck and happy flashing!