better AHCI error reporting to BASIC

Author: braindigitalis

include/ahci.h

@@ -11,6 +11,7 @@
 #pragma once
 
 #include <kernel.h>
+#include <scsi.h>
 
 /**
  * @brief Frame Information Structure (FIS) type identifiers.
@@ -331,8 +332,11 @@ typedef struct ahci_hba_cmd_tbl_t {
 
 /* ----------------------------- Interrupt/status and ATA opcodes ----------------------------- */
 
-/** @brief PxIS: Task File Error Status (TFES). */
-#define HBA_PxIS_TFES (1 << 30)
+#define HBA_PxIS_TFES	(1 << 30)   /** Task file error */
+#define HBA_PxIS_IFS	(1u << 27)  /* Interface fatal error */
+#define HBA_PxIS_HBDS	(1u << 28)  /* Host bus data error */
+#define HBA_PxIS_HBFS	(1u << 29)  /* Host bus fatal error */
+
 /** @brief ATA command: READ DMA EXT (48-bit). */
 #define ATA_CMD_READ_DMA_EX 0x25
 /** @brief ATA command: WRITE DMA EXT (48-bit). */
@@ -392,7 +396,7 @@ int find_cmdslot(ahci_hba_port_t *port, ahci_hba_mem_t *abar);
  * @param abar AHCI HBA memory block.
  * @return true on success, false on error.
  */
-bool ahci_read(ahci_hba_port_t *port, uint64_t start, uint32_t count, uint16_t *buf, ahci_hba_mem_t* abar);
+bool ahci_read(ahci_hba_port_t *port, uint64_t start, uint32_t count, char *buf, ahci_hba_mem_t* abar);
 
 /**
  * @brief Write to a SATA block device via DMA.
@@ -414,7 +418,7 @@ bool ahci_write(ahci_hba_port_t *port, uint64_t start, uint32_t count, char *buf
  * @param abar AHCI HBA memory block.
  * @return true on success, false on error.
  */
-bool ahci_atapi_read(ahci_hba_port_t *port, uint64_t start, uint32_t count, uint16_t *buf, ahci_hba_mem_t* abar);
+bool ahci_atapi_read(ahci_hba_port_t *port, uint64_t start, uint32_t count, char *buf, ahci_hba_mem_t* abar);
 
 /**
  * @brief Query capacity (in bytes) from a SATA device using IDENTIFY data.
@@ -466,27 +470,206 @@ int storage_device_ahci_block_read(void* dev, uint64_t start, uint32_t bytes, un
  */
 int storage_device_ahci_block_write(void* dev, uint64_t start, uint32_t bytes, const unsigned char* buffer);
 
-
+/**
+ * @brief Wait until the AHCI port and attached device are ready to accept a new command.
+ * @param port AHCI HBA port.
+ * @return true if ready, false on timeout or fatal port state.
+ */
 bool wait_for_ready(ahci_hba_port_t* port);
+
+/**
+ * @brief Fill one PRDT entry in the command table.
+ * @param cmdtbl Command table to modify.
+ * @param index PRDT entry index to fill.
+ * @param address Physical or DMA-able address of the data buffer.
+ * @param byte_count Number of bytes to transfer (1..4MiB per entry, device-dependent).
+ * @param interrupt Set true to request interrupt on completion for this PRDT entry.
+ */
 void fill_prdt(ahci_hba_cmd_tbl_t* cmdtbl, size_t index, void* address, uint32_t byte_count, bool interrupt);
+
+/**
+ * @brief Obtain and initialise a command header for a slot.
+ * @param port AHCI HBA port.
+ * @param slot Command slot number (0..31).
+ * @param write Set true for host-to-device (write), false for device-to-host (read).
+ * @param atapi Set true for ATAPI packet command, false for ATA.
+ * @param prdtls Number of PRDT entries to advertise (PRDTL).
+ * @return Pointer to the prepared command header.
+ */
 ahci_hba_cmd_header_t* get_cmdheader_for_slot(ahci_hba_port_t* port, size_t slot, bool write, bool atapi, uint16_t prdtls);
+
+/**
+ * @brief Return the command table for a header and clear CFIS/ATAPI/reserved regions.
+ * @param cmdheader Command header whose table will be accessed.
+ * @return Pointer to the command table.
+ */
 ahci_hba_cmd_tbl_t* get_and_clear_cmdtbl(ahci_hba_cmd_header_t* cmdheader);
+
+/**
+ * @brief Prepare a Register H2D FIS in the command table.
+ * @param cmdtbl Command table to place the FIS into.
+ * @param type FIS type (e.g., FIS_TYPE_REG_H2D).
+ * @param command ATA/ATAPI command opcode.
+ * @param feature_low Feature low byte.
+ * @return Pointer to the FIS within the command table.
+ */
 ahci_fis_reg_h2d_t* setup_reg_h2d(ahci_hba_cmd_tbl_t* cmdtbl, uint8_t type, uint8_t command, uint8_t feature_low);
+
+/**
+ * @brief Fill LBA and sector count fields in a Register H2D FIS.
+ * @param cmdfis Pointer to the FIS previously created by setup_reg_h2d.
+ * @param start Starting LBA.
+ * @param count Sector count (device logical block units).
+ */
 void fill_reg_h2c(ahci_fis_reg_h2d_t* cmdfis, uint64_t start, uint16_t count);
+
+/**
+ * @brief Issue a prepared command in the given slot by setting PxCI.
+ * @param port AHCI HBA port.
+ * @param slot Command slot number (0..31).
+ */
 void issue_command_to_slot(ahci_hba_port_t *port, uint8_t slot);
+
+/**
+ * @brief Wait for a command slot to complete and detect transport/taskfile errors.
+ * @param port AHCI HBA port.
+ * @param slot Command slot number (0..31).
+ * @param function Short label used for diagnostics/logging.
+ * @return true on success, false if a taskfile/transport error occurred (error already logged).
+ */
 bool wait_for_completion(ahci_hba_port_t* port, uint8_t slot, const char* function);
+
+/**
+ * @brief Convenience wrapper to issue a command and wait for completion.
+ * @param port AHCI HBA port.
+ * @param slot Command slot number (0..31).
+ * @param function Short label used for diagnostics/logging.
+ * @return true on success, false on error (error already logged).
+ */
 bool issue_and_wait(ahci_hba_port_t* port, uint8_t slot, const char* function);
+
+/**
+ * @brief Trim trailing ASCII spaces from a NUL-terminated string in place.
+ * @param s String buffer to modify.
+ */
 void trim_trailing_spaces(char *s);
+
+/**
+ * @brief Build a human-readable ATAPI device label from INQUIRY data.
+ * @param sd Storage device object to receive the label.
+ * @param inq 36+ byte SCSI INQUIRY response buffer.
+ */
 void build_atapi_label(struct storage_device_t *sd, const uint8_t *inq);
 
+/**
+ * @brief Eject removable media from an ATAPI device (ALLOW removal then START STOP with LOEJ).
+ * @param port AHCI HBA port for the device.
+ * @param abar AHCI HBA memory (ABAR) pointer.
+ * @return true on command acceptance, false on error (caller may fetch sense).
+ */
 bool atapi_eject(ahci_hba_port_t *port, ahci_hba_mem_t *abar);
-bool ahci_read(ahci_hba_port_t *port, uint64_t start, uint32_t count, uint16_t *buf, ahci_hba_mem_t* abar);
-bool ahci_write(ahci_hba_port_t *port, uint64_t start, uint32_t count, char *buf, ahci_hba_mem_t* abar);
-bool ahci_atapi_read(ahci_hba_port_t *port, uint64_t start, uint32_t count, uint16_t *buf, ahci_hba_mem_t* abar);
-uint64_t ahci_read_size(ahci_hba_port_t *port, ahci_hba_mem_t* abar);
+
+/**
+ * @brief Issue IDENTIFY (ATA or ATAPI) and copy the 512-byte identify page to out.
+ * @param port AHCI HBA port.
+ * @param abar AHCI HBA memory (ABAR) pointer.
+ * @param out Destination buffer for identify data (512 bytes).
+ * @return true on success, false on error.
+ */
 bool ahci_identify_page(ahci_hba_port_t *port, ahci_hba_mem_t *abar, uint8_t *out);
+
+/**
+ * @brief Issue ATAPI INQUIRY (0x12) and copy the response.
+ * @param port AHCI HBA port.
+ * @param abar AHCI HBA memory (ABAR) pointer.
+ * @param out Destination buffer for INQUIRY data.
+ * @param len Allocation length requested and number of bytes to copy.
+ * @return true on success, false on error (caller may use sense mapping).
+ */
 bool atapi_enquiry(ahci_hba_port_t *port, ahci_hba_mem_t *abar, uint8_t *out, uint8_t len);
 
+/**
+ * @brief Map AHCI/AHCI-ATA/ATAPI latched status on a port to a fixed fs_error_t without performing I/O.
+ * @param port AHCI HBA port; uses PxIS/PxSERR/PxTFD/PxSIG snapshots.
+ * @return fs_error_t value describing the failure class.
+ */
+int ahci_classify_error(ahci_hba_port_t* port);
+
+/**
+ * @brief Map SCSI/ATAPI sense (sense key, ASC, ASCQ) to a fixed fs_error_t.
+ * @param sense_key SCSI sense key.
+ * @param additional_sense_code Additional Sense Code (ASC).
+ * @param additional_sense_code_qualifier Additional Sense Code Qualifier (ASCQ).
+ * @return fs_error_t value describing the failure class.
+ */
+int scsi_map_sense_to_fs_error(scsi_sense_key_t sense_key, scsi_additional_sense_code_t additional_sense_code, scsi_additional_sense_code_qualifier_t additional_sense_code_qualifier);
+
+/**
+ * @brief Issue ATAPI REQUEST SENSE (6) and copy sense data to the caller buffer.
+ * @param port AHCI HBA port.
+ * @param abar AHCI HBA memory (ABAR) pointer.
+ * @param out Destination buffer for sense data.
+ * @param out_len Allocation length requested (typically 18).
+ * @return true on success, false on failure to obtain sense data.
+ */
+bool atapi_request_sense6(ahci_hba_port_t* port, ahci_hba_mem_t* abar, uint8_t* out, uint8_t out_len);
+
+/**
+ * @brief Extract sense key, ASC and ASCQ from a fixed-format (0x70/0x71) REQUEST SENSE buffer.
+ * @param buf Sense buffer (>= 14 bytes, typically 18).
+ * @param sense_key Output: sense key.
+ * @param additional_sense_code Output: ASC.
+ * @param additional_sense_code_qualifier Output: ASCQ.
+ */
+void scsi_extract_fixed_sense(const uint8_t* buf, scsi_sense_key_t* sense_key, scsi_additional_sense_code_t* additional_sense_code, scsi_additional_sense_code_qualifier_t* additional_sense_code_qualifier);
+
+/**
+ * @brief Handle ATAPI CHECK CONDITION by issuing REQUEST SENSE, mapping to fs_error_t, logging a single line, and returning false.
+ * @param port AHCI HBA port.
+ * @param abar AHCI HBA memory (ABAR) pointer.
+ * @param function Short label used for diagnostics/logging.
+ * @return Always false to simplify call-sites that branch on failure.
+ */
+bool atapi_handle_check_condition(ahci_hba_port_t* port, ahci_hba_mem_t* abar, const char* function);
+
+
+/**
+ * @brief Map AHCI/AHCI-ATA/ATAPI status to a fixed fs_error_t.
+ *
+ * Uses PxIS priority: HBFS → HBDS → IFS → TFES. For TFES, inspects PxTFD ERR bits.
+ * For ATAPI, returns FS_ERR_ATAPI_CHECK on TFES so the caller can issue REQUEST SENSE.
+ *
+ * This function performs no I/O; it only interprets the latched registers you pass in.
+ */
+int ahci_classify_error(ahci_hba_port_t* port);
+
+/**
+ * @brief Map SCSI/ATAPI sense (SK/ASC/ASCQ) to fs_error_t with fixed message.
+ */
+int scsi_map_sense_to_fs_error(scsi_sense_key_t sense_key, scsi_additional_sense_code_t additional_sense_code, scsi_additional_sense_code_qualifier_t additional_sense_code_qualifier);
+
+/**
+ * @brief Issue ATAPI REQUEST SENSE (6) and copy sense data to 'out'.
+ * Expects 'out_len' >= 18 for standard fixed-format sense.
+ * Returns true on success (command accepted and data DMA'd), false on failure.
+ */
+bool atapi_request_sense6(ahci_hba_port_t* port, ahci_hba_mem_t* abar, uint8_t* out, uint8_t out_len);
+
+/**
+ * @brief Extract SK/ASC/ASCQ from a fixed-format (0x70/0x71) REQUEST SENSE buffer.
+ * Caller guarantees 'buf' points to at least 14 bytes (we usually pass 18).
+ */
+void scsi_extract_fixed_sense(const uint8_t* buf, scsi_sense_key_t* sense_key, scsi_additional_sense_code_t* additional_sense_code, scsi_additional_sense_code_qualifier_t* additional_sense_code_qualifier);
+
+/**
+ * @brief Convenience helper for ATAPI CHECK CONDITION paths.
+ * Issues REQUEST SENSE, extracts and maps sense, logs a single line, then returns false.
+ *
+ * Always returns false so call-sites can simply: if (!atapi_handle_check_condition(...)) return false;
+ * If REQUEST SENSE itself fails, logs a generic timeout/hardware error.
+ */
+bool atapi_handle_check_condition(ahci_hba_port_t* port, ahci_hba_mem_t* abar, const char* function);
+
 /* ----------------------------- Layout sanity checks ----------------------------- */
 
 /** @brief Compile-time size check: command header must be 0x20 bytes. */

include/ata.h

@@ -12,4 +12,15 @@
 #define		ATA_IDENT_MAX_LBA	120
 #define		ATA_IDENT_MAX_LBA_EXT	200
 
+/* ATA Error Register bits */
+#define ATA_ERR_AMNF   0x01  /* Address mark not found (obsolete, legacy) */
+#define ATA_ERR_TK0NF  0x02  /* Track 0 not found (obsolete, legacy) */
+#define ATA_ERR_ABRT   0x04  /* Aborted command (illegal/unsupported) */
+#define ATA_ERR_MCR    0x08  /* Media change request (obsolete, legacy) */
+#define ATA_ERR_IDNF   0x10  /* ID not found (LBA not found) */
+#define ATA_ERR_MC     0x20  /* Media changed */
+#define ATA_ERR_UNC    0x40  /* Uncorrectable data error */
+#define ATA_ERR_ICRC   0x80  /* Interface CRC error / bad sector transfer */
+
+
 void init_ide();

include/filesystem.h

@@ -84,6 +84,18 @@ typedef enum fs_error_t {
 	FS_ERR_BAD_CLUSTER,
 	FS_ERR_INTERNAL,
 	FS_ERR_OUT_OF_BOUNDS,
+	FS_ERR_AHCI_HOSTBUS_FATAL,
+	FS_ERR_AHCI_HOSTBUS_DATA,
+	FS_ERR_AHCI_LINK_ERROR,
+	FS_ERR_AHCI_TASKFILE,
+	FS_ERR_ATAPI_CHECK,
+	FS_ERR_TIMEOUT,
+	FS_ERR_NO_MEDIA,
+	FS_ERR_DEVICE_LOCKED,
+	FS_ERR_DEVICE_BUSY,
+	FS_ERR_DEVICE_UNSUPPORTED,
+	FS_ERR_HW_ERROR,
+	FS_ERR_DATA_ERROR,
 } fs_error_t;
 
 /**

include/random.h

@@ -12,6 +12,16 @@
 #define RAND_MAX_ENTROPY	(size_t)24
 #define RAND_MAX		SIZE_MAX
 
+#define SAMPLE_FROM_BUFFER(p) \
+	(((uint64_t)((const uint8_t*)(p))[0] << 56) | \
+	((uint64_t)((const uint8_t*)(p))[1] << 48) | \
+	((uint64_t)((const uint8_t*)(p))[2] << 40) | \
+	((uint64_t)((const uint8_t*)(p))[3] << 32) | \
+	((uint64_t)((const uint8_t*)(p))[4] << 24) | \
+	((uint64_t)((const uint8_t*)(p))[5] << 16) | \
+	((uint64_t)((const uint8_t*)(p))[6] << 8) | \
+	((uint64_t)((const uint8_t*)(p))[7]))
+
 typedef struct mt_rand_t {
 	uint32_t mt[STATE_VECTOR_LENGTH];
 	int index;

include/scsi.h

@@ -18,10 +18,46 @@
 #define SCSI_OP_WRITE_16              0x8A
 #define SCSI_OP_SERVICE_ACTION_IN_16  0x9E  /* use SA=0x10 for READ CAPACITY(16) */
 
+typedef enum scsi_sense_key_t {
+	SCSI_SK_NO_SENSE		= 0x00,
+	SCSI_SK_RECOVERED_ERROR		= 0x01,
+	SCSI_SK_NOT_READY		= 0x02,
+	SCSI_SK_MEDIUM_ERROR		= 0x03,
+	SCSI_SK_HARDWARE_ERROR		= 0x04,
+	SCSI_SK_ILLEGAL_REQUEST		= 0x05,
+	SCSI_SK_UNIT_ATTENTION		= 0x06,
+	SCSI_SK_DATA_PROTECT		= 0x07,
+	SCSI_SK_BLANK_CHECK		= 0x08,
+	SCSI_SK_VENDOR_SPECIFIC		= 0x09,
+	SCSI_SK_COPY_ABORTED		= 0x0A,
+	SCSI_SK_ABORTED_COMMAND		= 0x0B,
+	SCSI_SK_VOLUME_OVERFLOW		= 0x0D,
+	SCSI_SK_MISCOMPARE		= 0x0E,
+} scsi_sense_key_t;
+
+typedef enum scsi_additional_sense_code_t {
+	SCSI_ASC_LUN_NOT_READY		= 0x04,
+	SCSI_ASC_INVALID_FIELD		= 0x24,
+	SCSI_ASC_WRITE_PROTECTED	= 0x27,
+	SCSI_ASC_MEDIA_CHANGED		= 0x28,
+	SCSI_ASC_MEDIUM_NOT_PRESENT	= 0x3A,
+	SCSI_ASC_ANY			= 0xFF, /* Wildcard */
+} scsi_additional_sense_code_t;
+
+typedef enum scsi_additional_sense_code_qualifier_t {
+	SCSI_ASCQ_BECOMING_READY	= 0x01,
+	SCSI_ASCQ_INIT_REQUIRED		= 0x02,
+	SCSI_ASCQ_MANUAL_INTERVENTION	= 0x03,
+	SCSI_ASCQ_MEDIUM_NOT_PRESENT	= 0x00,
+	SCSI_ASCQ_MEDIA_CHANGED		= 0x00,
+	SCSI_ASCQ_WRITE_PROTECTED	= 0x00,
+	SCSI_ASCQ_ANY			= 0xFF, /* Wildcard */
+} scsi_additional_sense_code_qualifier_t;
+
 /* INQUIRY(6) — 6 bytes */
 typedef struct __attribute__((packed)) scsi_cdb_inquiry6 {
 	uint8_t  opcode;       /* 0x12 */
-	uint8_t  evpd;         /* bit0 = EVPD; you use 0 */
+	uint8_t  evpd;         /* bit0 = EVPD */
 	uint8_t  page_code;    /* usually 0 */
 	uint8_t  reserved;     /* 0 */
 	uint8_t  alloc_len;    /* 1-byte allocation length */
@@ -31,7 +67,7 @@ typedef struct __attribute__((packed)) scsi_cdb_inquiry6 {
 /* READ(12) — 12 bytes; LBA and transfer length are big-endian */
 typedef struct __attribute__((packed)) scsi_cdb_read12 {
 	uint8_t  opcode;       /* 0xA8 */
-	uint8_t  flags;        /* DPO/FUA/etc; you use 0 */
+	uint8_t  flags;        /* DPO/FUA/etc */
 	uint32_t lba_be;       /* big-endian */
 	uint32_t xfer_be;      /* big-endian (blocks) */
 	uint8_t  group;        /* 0 */
@@ -61,7 +97,7 @@ typedef struct __attribute__((packed)) scsi_cdb_request_sense6 {
 /* START STOP UNIT (6) — opcode 0x1B */
 typedef struct __attribute__((packed)) scsi_cdb_start_stop_unit6 {
 	uint8_t opcode;      /* 0x1B */
-	uint8_t immed;       /* bit0 IMMED if you need it */
+	uint8_t immed;       /* bit0 IMMED */
 	uint8_t rsv1;
 	uint8_t rsv2;
 	uint8_t power;       /* bits: LOEJ/START/POWER-COND */

src/block/ahci/enquiry.c

@@ -24,7 +24,7 @@ bool atapi_enquiry(ahci_hba_port_t *port, ahci_hba_mem_t *abar, uint8_t *out, ui
 	cdb->alloc_len = len;
 
 	if (!issue_and_wait(port, slot, "inquiry")) {
-		return false;
+		return atapi_handle_check_condition(port, abar, "inquiry");
 	}
 
 	memcpy(out, aligned_read_buf, len);