Kernel/USB: Add a crude USB MassStorage driver :^)

Kernel/Devices/Storage/USB/BulkSCSIInterface.cpp

@@ -0,0 +1,125 @@
+/*
+ * Copyright (c) 2023, Leon Albrecht <leon.a@serenityos.org>
+ *
+ * SPDX-License-Identifier: BSD-2-Clause
+ */
+
+#include <Kernel/Bus/USB/USBController.h>
+#include <Kernel/Devices/Storage/USB/BulkSCSIInterface.h>
+#include <Kernel/Devices/Storage/USB/SCSIComands.h>
+
+namespace Kernel::USB {
+
+BulkSCSIInterface::BulkSCSIInterface(LUNAddress logical_unit_number_address, u32 hardware_relative_controller_id, size_t sector_size, u64 max_addressable_block, USB::Device& device, NonnullOwnPtr<BulkInPipe> in_pipe, NonnullOwnPtr<BulkOutPipe> out_pipe)
+    : StorageDevice(logical_unit_number_address, hardware_relative_controller_id, sector_size, max_addressable_block)
+    , m_device(device)
+    , m_in_pipe(move(in_pipe))
+    , m_out_pipe(move(out_pipe))
+{
+}
+
+void BulkSCSIInterface::start_request(AsyncBlockDeviceRequest& request)
+{
+    if (request.request_type() == AsyncBlockDeviceRequest::RequestType::Read) {
+        if (do_read(request.block_index(), request.block_count(), request.buffer(), request.buffer_size()).is_error()) {
+            request.complete(AsyncDeviceRequest::RequestResult::Failure);
+        } else {
+            request.complete(AsyncDeviceRequest::RequestResult::Success);
+        }
+    } else {
+        if (do_write(request.block_index(), request.block_count(), request.buffer(), request.buffer_size()).is_error()) {
+            request.complete(AsyncDeviceRequest::RequestResult::Failure);
+        } else {
+            request.complete(AsyncDeviceRequest::RequestResult::Success);
+        }
+    }
+}
+
+ErrorOr<void> BulkSCSIInterface::do_read(u32 block_index, u32 block_count, UserOrKernelBuffer& buffer, size_t)
+{
+    // FIXME: Error Handling and proper device reset on exit
+    CommandBlockWrapper command;
+    SCSI::Read10 read_command;
+
+    u32 block_index_to_read = block_index;
+    u32 blocks_read = 0;
+    UserOrKernelBuffer destination_buffer = buffer;
+    while (blocks_read < block_count) {
+        read_command.logical_block_address = block_index_to_read;
+
+        u16 transfer_length_bytes = min((block_count - blocks_read) * block_size(), AK::NumericLimits<u16>::max());
+
+        read_command.transfer_length = transfer_length_bytes / block_size();
+
+        command.transfer_length = transfer_length_bytes;
+        command.direction = CBWDirection::DataIn;
+        command.set_command(read_command);
+
+        TRY(m_out_pipe->submit_bulk_out_transfer(sizeof(command), &command));
+
+        TRY(m_in_pipe->submit_bulk_in_transfer(transfer_length_bytes, destination_buffer));
+
+        CommandStatusWrapper status;
+        TRY(m_in_pipe->submit_bulk_in_transfer(sizeof(status), &status));
+
+        if (status.status != CSWStatus::Passed) {
+            // FIXME: Actually handle the error
+            //        See usbmassbulk 5.3, 6.4 and 6.5
+            dmesgln("SCSI/BBB: Read failed with code {}", to_underlying(status.status));
+            return EIO;
+        }
+
+        u32 bytes_transferred = transfer_length_bytes - status.data_residue;
+        u32 blocks_read_in_transfer = bytes_transferred / block_size();
+
+        blocks_read += blocks_read_in_transfer;
+        block_index_to_read += blocks_read_in_transfer;
+    }
+
+    return {};
+}
+
+ErrorOr<void> BulkSCSIInterface::do_write(u32 block_index, u32 block_count, UserOrKernelBuffer& buffer, size_t)
+{
+    // FIXME: Error Handling and proper device reset on exit
+
+    CommandBlockWrapper command;
+    SCSI::Write10 read_command;
+
+    u32 block_index_to_read = block_index;
+    u32 blocks_read = 0;
+    UserOrKernelBuffer destination_buffer = buffer;
+    while (blocks_read < block_count) {
+        read_command.logical_block_address = block_index_to_read;
+
+        u16 transfer_length_bytes = min((block_count - blocks_read) * block_size(), AK::NumericLimits<u16>::max());
+
+        read_command.transfer_length = transfer_length_bytes / block_size();
+
+        command.transfer_length = transfer_length_bytes;
+        command.direction = CBWDirection::DataOut;
+        command.set_command(read_command);
+
+        TRY(m_out_pipe->submit_bulk_out_transfer(sizeof(command), &command));
+
+        TRY(m_out_pipe->submit_bulk_out_transfer(transfer_length_bytes, destination_buffer));
+
+        CommandStatusWrapper status;
+        TRY(m_in_pipe->submit_bulk_in_transfer(sizeof(status), &status));
+
+        if (status.status != CSWStatus::Passed) {
+            // FIXME: Actually handle the error
+            //        See usbmassbulk 5.3, 6.4 and 6.5
+            dmesgln("SCSI/BBB: Write failed with code {}", to_underlying(status.status));
+            return EIO;
+        }
+
+        u32 bytes_transferred = transfer_length_bytes - status.data_residue;
+        u32 blocks_read_in_transfer = bytes_transferred / block_size();
+        blocks_read += blocks_read_in_transfer;
+        block_index_to_read += blocks_read_in_transfer;
+    }
+
+    return {};
+}
+}

Kernel/Devices/Storage/USB/BulkSCSIInterface.h

@@ -0,0 +1,85 @@
+/*
+ * Copyright (c) 2023, Leon Albrecht <leon.a@serenityos.org>
+ *
+ * SPDX-License-Identifier: BSD-2-Clause
+ */
+
+#pragma once
+
+#include <AK/IntrusiveList.h>
+#include <Kernel/Bus/USB/USBDevice.h>
+#include <Kernel/Bus/USB/USBPipe.h>
+#include <Kernel/Devices/Storage/StorageDevice.h>
+
+namespace Kernel::USB {
+
+enum class CBWDirection : u8 {
+    DataOut = 0,
+    DataIn = 1
+};
+
+struct CommandBlockWrapper {
+    LittleEndian<u32> signature { 0x43425355 };
+    LittleEndian<u32> tag { 0 };
+    LittleEndian<u32> transfer_length { 0 };
+    union {
+        u8 flags { 0 };
+        struct {
+            u8 flag_reserved : 6;
+            u8 flag_obsolete : 1;
+            CBWDirection direction : 1;
+        };
+    };
+    u8 lun { 0 };            // only 4 bits
+    u8 command_length { 0 }; // 5 bits, range 1-16
+    u8 command_block[16] { 0 };
+
+    template<typename T>
+    requires(sizeof(T) <= 16)
+    void set_command(T const& command)
+    {
+        command_length = sizeof(command);
+        memcpy(&command_block, &command, sizeof(command));
+    }
+};
+static_assert(AssertSize<CommandBlockWrapper, 31>());
+
+enum class CSWStatus : u8 {
+    Passed = 0x00,
+    Failed = 0x01,
+    PhaseError = 0x02
+};
+
+struct CommandStatusWrapper {
+    LittleEndian<u32> signature;
+    LittleEndian<u32> tag;
+    LittleEndian<u32> data_residue;
+    CSWStatus status;
+};
+static_assert(AssertSize<CommandStatusWrapper, 13>());
+
+class BulkSCSIInterface : public StorageDevice {
+    // https://www.usb.org/sites/default/files/usbmassbulk_10.pdf
+public:
+    BulkSCSIInterface(LUNAddress logical_unit_number_address, u32 hardware_relative_controller_id, size_t sector_size, u64 max_addressable_block, USB::Device& device, NonnullOwnPtr<BulkInPipe> in_pipe, NonnullOwnPtr<BulkOutPipe> out_pipe);
+
+    USB::Device const& device() const { return m_device; }
+
+    virtual void start_request(AsyncBlockDeviceRequest&) override;
+    virtual CommandSet command_set() const override { return CommandSet::SCSI; }
+
+private:
+    USB::Device& m_device;
+    NonnullOwnPtr<BulkInPipe> m_in_pipe;
+    NonnullOwnPtr<BulkOutPipe> m_out_pipe;
+
+    ErrorOr<void> do_read(u32 block_index, u32 block_count, UserOrKernelBuffer& buffer, size_t buffer_size);
+    ErrorOr<void> do_write(u32 block_index, u32 block_count, UserOrKernelBuffer& buffer, size_t buffer_size);
+
+    IntrusiveListNode<BulkSCSIInterface, NonnullLockRefPtr<BulkSCSIInterface>> m_list_node;
+
+public:
+    using List = IntrusiveList<&BulkSCSIInterface::m_list_node>;
+};
+
+}

Kernel/Devices/Storage/USB/Codes.h

@@ -0,0 +1,108 @@
+/*
+ * Copyright (c) 2023, Leon Albrecht <leon.a@serenityos.org>
+ *
+ * SPDX-License-Identifier: BSD-2-Clause
+ */
+
+#pragma once
+
+#include <AK/StringView.h>
+#include <AK/Types.h>
+
+namespace Kernel::USB::MassStorage {
+// https://www.usb.org/sites/default/files/Mass_Storage_Specification_Overview_v1.4_2-19-2010.pdf
+// 2
+enum class SubclassCode : u8 {
+    NotReported = 0x00,
+    RBC = 0x01,
+    MMC5 = 0x02, // ATAPI
+    Obsolete_QIC157 = 0x03,
+    UFI = 0x04, // Floppy
+    Obsolete_SFF8070i = 0x05,
+    SCSI_transparent = 0x06,
+    LSD_FS = 0x07,
+    IEEE1667 = 0x08,
+    // Reserved: 0x09 - 0xFE
+    VendorSpecific = 0xFF
+};
+
+constexpr StringView subclass_string(SubclassCode code)
+{
+    switch (code) {
+    case SubclassCode::NotReported:
+        return "Not Reported"sv;
+    case SubclassCode::RBC:
+        return "RBC"sv;
+    case SubclassCode::MMC5:
+        return "MMC-5 (ATAPI)"sv;
+    case SubclassCode::Obsolete_QIC157:
+        return "QIC157 (Obsolete)"sv;
+    case SubclassCode::UFI:
+        return "UFI"sv;
+    case SubclassCode::Obsolete_SFF8070i:
+        return "SFF8070i (Obsolete)"sv;
+    case SubclassCode::SCSI_transparent:
+        return "SCSI-transparent"sv;
+    case SubclassCode::LSD_FS:
+        return "LSD FS"sv;
+    case SubclassCode::IEEE1667:
+        return "IEEE1667"sv;
+    case SubclassCode::VendorSpecific:
+        return "Vendor Specific"sv;
+    }
+
+    return "Reserved"sv;
+}
+
+// 3
+enum class TransportProtocol : u8 {
+    CBI_completion_interrupt = 0x00,    // Control/Bulk/Interrupt
+    CBI_no_completion_interrupt = 0x01, // Control/Bulk/Interrupt
+    Obsolete = 0x02,
+    // Reserved: 0x03 - 0x4F
+    BBB = 0x50, // Bulk-only
+    // Reserved: 0x51 - 0x61
+    UAS = 0x62,
+    // Reserved: 0x63 - 0xFE
+    VendorSpecific = 0xFF
+};
+
+constexpr StringView transport_protocol_string(TransportProtocol protocol)
+{
+    switch (protocol) {
+    case TransportProtocol::CBI_completion_interrupt:
+        return "Control/Bulk/Interrupt with completion interrupt"sv;
+    case TransportProtocol::CBI_no_completion_interrupt:
+        return "Control/Bulk/Interrupt without completion interrupt"sv;
+    case TransportProtocol::Obsolete:
+        return "Obsolete"sv;
+    case TransportProtocol::BBB:
+        return "Bulk only"sv;
+    case TransportProtocol::UAS:
+        return "UAS"sv;
+    case TransportProtocol::VendorSpecific:
+        return "Vendor Specific"sv;
+    }
+
+    return "Reserved"sv;
+}
+
+// 4
+enum class RequestCodes : u8 {
+    ADSC = 0x00, // Accept Device Specific Command (CBI) - also alias USB-request 00h Get Status
+    // Reserved/alias USB-bRequest: 0x01 - 0x0D
+    // Reserved: 0x0E - 0XFB
+    GetRequest = 0xFC,
+    PutRequest = 0xFD,
+    GetMaxLun = 0xFE,               // GML (BBB)
+    BulkOnlyMassStorageReset = 0xFF // BOMSR (BBB)
+};
+
+// 5
+enum class ClassSpecificDescriptorCodes : u8 {
+    // Undefined by Mass Storage: 0x00 - 0x23
+    PipeUsageClassSpecific = 0x24 // UAS
+    // Undefined by Mass Storage: 0x25 - 0xFF
+};
+
+}

Kernel/Devices/Storage/USB/SCSIComands.h

@@ -0,0 +1,72 @@
+/*
+ * Copyright (c) 2023, Leon Albrecht <leon.a@serenityos.org>
+ *
+ * SPDX-License-Identifier: BSD-2-Clause
+ */
+
+#pragma once
+
+#include <AK/Endian.h>
+#include <AK/StdLibExtraDetails.h>
+#include <AK/Types.h>
+
+// https://www.seagate.com/files/staticfiles/support/docs/manual/Interface%20manuals/100293068j.pdf
+
+namespace Kernel::SCSI {
+// 3.22.1
+struct ReadCapacity10 {
+    u8 opcode { 0x25 };
+    u8 reserved1 { 0 };
+    BigEndian<u32> oboslete_logical_block_address { 0 };
+    u16 reserved2 { 0 };
+    u8 reserved3 { 0 };
+    u8 control { 0 };
+};
+static_assert(AssertSize<ReadCapacity10, 10>());
+// 3.22.2
+struct ReadCapacity10Parameters {
+    BigEndian<u32> block_count;
+    BigEndian<u32> block_size;
+};
+static_assert(AssertSize<ReadCapacity10Parameters, 8>());
+
+// 3.16
+struct Read10 {
+    u8 operation_code { 0x28 };
+    union {
+        u8 settings { 0 };
+        struct {
+            u8 obsolete : 2;
+            u8 rarc : 1;
+            u8 fua : 1;
+            u8 dpo : 1;
+            u8 rdprotect : 3;
+        };
+    };
+    BigEndian<u32> logical_block_address;
+    u8 group_number { 0 }; // only bottom 5 bits
+    BigEndian<u16> transfer_length;
+    u8 control { 0 };
+};
+static_assert(AssertSize<Read10, 10>());
+
+// 3.60
+struct Write10 {
+    u8 operation_code { 0x2A };
+    union {
+        u8 settings { 0 };
+        struct {
+            u8 obsolete : 2;
+            u8 reserved : 1;
+            u8 fua : 1;
+            u8 dpo : 1;
+            u8 wrprotect : 3;
+        };
+    };
+    BigEndian<u32> logical_block_address;
+    u8 group_number { 0 }; // only bottom 5 bits
+    BigEndian<u16> transfer_length;
+    u8 control { 0 };
+};
+static_assert(AssertSize<Read10, 10>());
+}