ez5n: clean up comments in header

Author: lifehackerhansol

blocksds/source/platform/ez5n/ez5n.c

@@ -57,7 +57,7 @@ void EZ5N_SDWriteSectors(u32 sector, u32 num_sectors, const void* buffer) {
 
         // Flush to disk
         // Should return 0 when done
-        while (EZ5N_SendCommand(EZ5N_CMD_SD_WRITE_FLUSH(sector, sector_count), 0x190))
+        while (EZ5N_SendCommand(EZ5N_CMD_SD_FLUSH_BUFFER(sector, sector_count), 0x190))
             ;
         sector += sector_count;
         num_sectors -= sector_count;

blocksds/source/platform/ez5n/ez5n.h

@@ -16,36 +16,51 @@
 #define NULL 0
 #endif
 
-// EZParallel defines
 // EZParallel MCCNT1 flags
+
+// Common flags set by all commands
 #define EZ5N_CTRL_BASE \
     (MCCNT1_RESET_OFF | MCCNT1_CMD_SCRAMBLE | MCCNT1_CLOCK_SCRAMBLER | MCCNT1_READ_DATA_DESCRAMBLE)
+
+// Flags when sending a command and retrieving a 4-byte response.
 #define EZ5N_CTRL_SEND_CMD (EZ5N_CTRL_BASE | MCCNT1_LATENCY2(24) | MCCNT1_LEN_4)
-#define EZ5N_CTRL_READ_SD (EZ5N_CTRL_BASE | MCCNT1_LATENCY2(26))
-#define EZ5N_CTRL_WRITE_SD \
-    (EZ5N_CTRL_BASE | MCCNT1_DIR_WRITE | MCCNT1_LATENCY2(26) | MCCNT1_LATENCY1(0x1FFF))
 
+// Flags when reading blocks of data.
+#define EZ5N_CTRL_READ_SD (EZ5N_CTRL_BASE | MCCNT1_LATENCY2(26))
 #define EZ5N_CTRL_READ_SD_512 (EZ5N_CTRL_READ_SD | MCCNT1_LEN_512)
 #define EZ5N_CTRL_READ_SD_1024 (EZ5N_CTRL_READ_SD | MCCNT1_LEN_1024)
 #define EZ5N_CTRL_READ_SD_2048 (EZ5N_CTRL_READ_SD | MCCNT1_LEN_2048)
 
+// Flags when writing blocks of data.
+// The original kernel did not set any LATENCY1; however, without it, intermittent
+// corruption occurs, therefore the maximum latency was added.
+#define EZ5N_CTRL_WRITE_SD \
+    (EZ5N_CTRL_BASE | MCCNT1_DIR_WRITE | MCCNT1_LATENCY2(26) | MCCNT1_LATENCY1(0x1FFF))
+
 // EZParallel MCCMDs
+
+// Retrieves the card hardware version.
 #define EZ5N_CMD_CARD_VERSION 0x3E00000000000000ull
+
+// Sends a FAT offset table to be used with hardware-backed retail cartridge emulation.
 #define EZ5N_CMD_SD_SEND_FAT_ENTRY 0xB100000100000000ull
-#define EZ5N_CMD_SD_READ_DATA 0xBA00000000000000ull
 
-// this reads 4 sectors???
+// Requests block reads from the SD card up to 4 sectors at a time.
 static inline u64 EZ5N_CMD_SD_READ_REQUEST(u32 sector, u32 num_sectors) {
     return (0xB9ull << 56) | ((u64)(num_sectors & 0xFF) << 32) | ((u64)sector);
 }
 
-// Writing seems to support up to 0x800 bytes
-// It appears to work from an internal buffer, and flushes afterwards.
+// Retrieve data blocks requested by EZ5N_CMD_SD_READ_REQUEST
+#define EZ5N_CMD_SD_READ_DATA 0xBA00000000000000ull
+
+// Sends data blocks to an index in the internal write buffer.
+// Up to 4 indices are supported; this means that 4 sectors can be written at a time.
 static inline u64 EZ5N_CMD_SD_WRITE_BUFFER(u32 buffer_index) {
     return (0xBBull << 56) | (1ull << 32) | ((u64)(buffer_index & 0xFF));
 }
 
-static inline u64 EZ5N_CMD_SD_WRITE_FLUSH(u32 sector, u32 num_sectors) {
+// Flushes the internal buffer to a given sector on the SD card.
+static inline u64 EZ5N_CMD_SD_FLUSH_BUFFER(u32 sector, u32 num_sectors) {
     return (0xBCull << 56) | ((u64)(num_sectors & 0xFF) << 32) | ((u64)sector);
 }