ublk 1.0.0

data/lib/ublk/params.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module UBLK
+  Params = Data.define(
+    :size, :logical_block_size, :physical_block_size, :max_io_bytes,
+    :read_only, :rotational, :discard
+  ) do
+    def initialize(size:, logical_block_size: 512, physical_block_size: 4096,
+                   max_io_bytes: 512 * 1024, read_only: false, rotational: false,
+                   discard: true)
+      [logical_block_size, physical_block_size].each do |block_size|
+        valid = block_size.is_a?(Integer) && block_size.between?(512, 4096) && (block_size & (block_size - 1)).zero?
+        raise ArgumentError, "block sizes must be powers of two between 512 and 4096" unless valid
+      end
+      raise ArgumentError, "physical block size must not be smaller than logical block size" if physical_block_size < logical_block_size
+      raise ArgumentError, "size must be aligned to the logical block size" unless (size % logical_block_size).zero?
+      raise ArgumentError, "max_io_bytes must be a positive multiple of 512" unless max_io_bytes.is_a?(Integer) && max_io_bytes.positive? && (max_io_bytes % 512).zero?
+      raise ArgumentError, "max_io_bytes must not exceed 32 MiB" if max_io_bytes > 32 * 1024 * 1024
+
+      super
+    end
+
+    def self.from_target(target, max_io_bytes: 512 * 1024)
+      new(
+        size: target.size,
+        logical_block_size: target.logical_block_size,
+        physical_block_size: target.physical_block_size,
+        max_io_bytes:,
+        read_only: target.read_only?,
+        rotational: target.rotational?,
+        discard: target.method(:discard).owner != Target || target.method(:write_zeroes).owner != Target
+      )
+    end
+  end
+end

data/lib/ublk/target.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module UBLK
+  class Target
+    attr_reader :size, :queues, :depth
+
+    def initialize(size:, queues: 1, depth: 128)
+      raise ArgumentError, "size must be a positive multiple of 512" unless size.is_a?(Integer) && size.positive? && (size % 512).zero?
+      raise ArgumentError, "queues must be between 1 and 4096" unless queues.is_a?(Integer) && queues.between?(1, 4096)
+      raise ArgumentError, "depth must be between 1 and 4096" unless depth.is_a?(Integer) && depth.between?(1, 4096)
+
+      @size = size
+      @queues = queues
+      @depth = depth
+    end
+
+    def read(_offset, _length)
+      raise NotImplementedError, "targets must implement #read"
+    end
+
+    def write(_offset, _data)
+      raise Errno::EROFS if read_only?
+
+      raise NotImplementedError, "targets must implement #write"
+    end
+
+    def flush = 0
+
+    def discard(_offset, _length)
+      raise Errno::EOPNOTSUPP
+    end
+
+    def write_zeroes(_offset, _length)
+      raise Errno::EOPNOTSUPP
+    end
+
+    def logical_block_size = 512
+    def physical_block_size = 4096
+    def read_only? = false
+    def rotational? = false
+  end
+end

data/lib/ublk/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module UBLK
+  VERSION = "1.0.0"
+end

data/lib/ublk.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require_relative "ublk/version"
+require_relative "ublk/target"
+require_relative "ublk/device_info"
+require_relative "ublk/params"
+
+module UBLK
+  class Error < StandardError; end
+  class UnsupportedError < Error; end
+  class DeviceError < Error; end
+
+  begin
+    require "ublk/ublk"
+  rescue LoadError => error
+    @native_load_error = error
+  end
+
+  class << self
+    attr_reader :native_load_error
+
+    def supported?
+      !!(defined?(Native) && Native.supported?)
+    end
+
+    def ensure_supported!
+      return if supported?
+
+      detail = native_load_error&.message || "/dev/ublk-control is unavailable"
+      raise UnsupportedError, "ublk requires Linux 6.6+, ublk_drv, and liburing (#{detail})"
+    end
+  end
+end
+
+require_relative "ublk/control"
+require_relative "ublk/device"

data/sig/ublk.rbs

@@ -0,0 +1,96 @@
+module UBLK
+  VERSION: String
+
+  class Error < StandardError
+  end
+
+  class UnsupportedError < Error
+  end
+
+  class DeviceError < Error
+  end
+
+  def self.supported?: () -> bool
+  def self.ensure_supported!: () -> nil
+  def self.native_load_error: () -> LoadError?
+
+  class Target
+    attr_reader size: Integer
+    attr_reader queues: Integer
+    attr_reader depth: Integer
+
+    def initialize: (size: Integer, ?queues: Integer, ?depth: Integer) -> void
+    def read: (Integer offset, Integer length) -> String
+    def write: (Integer offset, String data) -> Integer
+    def flush: () -> Integer
+    def discard: (Integer offset, Integer length) -> Integer
+    def write_zeroes: (Integer offset, Integer length) -> Integer
+    def logical_block_size: () -> Integer
+    def physical_block_size: () -> Integer
+    def read_only?: () -> bool
+    def rotational?: () -> bool
+  end
+
+  class DeviceInfo
+    attr_reader id: Integer
+    attr_reader queues: Integer
+    attr_reader depth: Integer
+    attr_reader state: Integer
+    attr_reader max_io_bytes: Integer
+    attr_reader pid: Integer
+    attr_reader flags: Integer
+    attr_reader owner_uid: Integer
+    attr_reader owner_gid: Integer
+
+    def path: () -> String
+    def char_path: () -> String
+    def self.from_native: (Array[Integer] values) -> DeviceInfo
+  end
+
+  class Params
+    attr_reader size: Integer
+    attr_reader logical_block_size: Integer
+    attr_reader physical_block_size: Integer
+    attr_reader max_io_bytes: Integer
+    attr_reader read_only: bool
+    attr_reader rotational: bool
+    attr_reader discard: bool
+
+    def initialize: (size: Integer, ?logical_block_size: Integer, ?physical_block_size: Integer, ?max_io_bytes: Integer, ?read_only: bool, ?rotational: bool, ?discard: bool) -> void
+    def self.from_target: (Target target, ?max_io_bytes: Integer) -> Params
+  end
+
+  class Control
+    SYSFS: String
+
+    def initialize: () -> void
+    def add_dev: (?id: Integer?, ?queues: Integer, ?depth: Integer, ?max_io_bytes: Integer, ?recovery: bool) -> DeviceInfo
+    def set_params: (Integer id, Params params) -> Params
+    def start_dev: (Integer id, ?pid: Integer) -> bool
+    def stop_dev: (Integer id) -> bool
+    def del_dev: (Integer id) -> bool
+    def start_user_recovery: (Integer id) -> bool
+    def end_user_recovery: (Integer id, ?pid: Integer) -> bool
+    def get_dev_info: (Integer id) -> DeviceInfo
+    def list: () -> Array[DeviceInfo]
+    def close: () -> nil
+  end
+
+  class Device
+    attr_reader target: Target
+    attr_reader info: DeviceInfo
+    attr_reader params: Params
+
+    def self.create: (Target target, ?id: Integer?, ?queues: Integer, ?depth: Integer, ?max_io_bytes: Integer, ?recovery: bool, ?mlock: bool) -> Device
+    def self.recover: (Target target, id: Integer, ?mlock: bool) -> Device
+    def self.list: () -> Array[DeviceInfo]
+    def self.delete_all!: () -> void
+    def id: () -> Integer
+    def path: () -> String
+    def char_path: () -> String
+    def start: (?threads: :auto | Integer) -> Device
+    def stop: () -> Device
+    def delete: () -> Device
+    def run: (?threads: :auto | Integer) -> Device
+  end
+end

data/tools/bench.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require "tempfile"
+require_relative "../examples/loop"
+
+abort "set UBLK_BENCH=1 inside a privileged Linux VM" unless ENV["UBLK_BENCH"] == "1"
+
+device = nil
+backing = nil
+at_exit do
+  device&.delete
+  backing&.close!
+end
+duration = Integer(ENV.fetch("UBLK_BENCH_SECONDS", "60"), 10)
+path = ENV["UBLK_BENCH_DEVICE"]
+if path
+  abort "UBLK_BENCH_DEVICE must be a block device" unless File.blockdev?(path)
+else
+  GC.stress = true if ENV["UBLK_BENCH_GC_STRESS"] == "1"
+  backing = Tempfile.new("ublk-bench")
+  backing.truncate(256 * 1024 * 1024)
+  device = UBLK::Device.create(LoopTarget.new(backing.path), depth: 128, mlock: false)
+  device.start
+  path = device.path
+end
+
+%w[randread randwrite read].each do |workload|
+  success = system(
+    "fio", "--name=#{workload}", "--filename=#{path}", "--direct=1", "--rw=#{workload}",
+    "--ioengine=io_uring", "--bs=4k", "--iodepth=32", "--runtime=#{duration}", "--time_based=1",
+    "--output-format=json"
+  )
+  abort "fio #{workload} failed" unless success
+end

data/tools/dump_constants.c

@@ -0,0 +1,19 @@
+#include <stdio.h>
+#include "../ext/ublk/compat.h"
+
+#define DUMP(value) printf("%s=%llu\n", #value, (unsigned long long)(value))
+
+int main(void)
+{
+  DUMP(UBLK_F_USER_COPY);
+  DUMP(UBLK_F_CMD_IOCTL_ENCODE);
+  DUMP(UBLK_F_USER_RECOVERY);
+  DUMP(UBLK_MAX_QUEUE_DEPTH);
+  DUMP(UBLKSRV_IO_BUF_OFFSET);
+  DUMP(UBLK_IO_OP_READ);
+  DUMP(UBLK_IO_OP_WRITE);
+  DUMP(UBLK_IO_OP_FLUSH);
+  DUMP(UBLK_IO_OP_DISCARD);
+  DUMP(UBLK_IO_OP_WRITE_ZEROES);
+  return 0;
+}

data/tools/vm/Makefile

@@ -0,0 +1,5 @@
+KVER ?= v6.12
+
+.PHONY: test
+test:
+	./run.sh $(KVER)

data/tools/vm/config-fragment

@@ -0,0 +1,4 @@
+CONFIG_BLK_DEV_UBLK=y
+CONFIG_BLK_DEV_LOOP=y
+CONFIG_EXT4_FS=y
+CONFIG_IO_URING=y

data/tools/vm/guest-test.sh

@@ -0,0 +1,6 @@
+#!/bin/sh
+set -eu
+
+modprobe ublk_drv
+export UBLK_SYSTEM_TEST=1
+exec bundle exec rake test:system

data/tools/vm/run.sh

@@ -0,0 +1,5 @@
+#!/bin/sh
+set -eu
+
+kernel=${1:-v6.12}
+exec vng -r "$kernel" --user root -- tools/vm/guest-test.sh

metadata

@@ -0,0 +1,75 @@
+--- !ruby/object:Gem::Specification
+name: ublk
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Yudai Takada
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: A native Ruby binding for Linux ublk using io_uring and UBLK_F_USER_COPY.
+email:
+- t.yudai92@gmail.com
+executables: []
+extensions:
+- ext/ublk/extconf.rb
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- Rakefile
+- examples/encrypted.rb
+- examples/fault_injection.rb
+- examples/http_disk.rb
+- examples/loop.rb
+- examples/ramdisk.rb
+- examples/tracing.rb
+- ext/ublk/compat.h
+- ext/ublk/constants.c
+- ext/ublk/control.c
+- ext/ublk/extconf.rb
+- ext/ublk/internal.h
+- ext/ublk/server.c
+- ext/ublk/ublk.c
+- lib/ublk.rb
+- lib/ublk/control.rb
+- lib/ublk/device.rb
+- lib/ublk/device_info.rb
+- lib/ublk/params.rb
+- lib/ublk/target.rb
+- lib/ublk/version.rb
+- sig/ublk.rbs
+- tools/bench.rb
+- tools/dump_constants.c
+- tools/vm/Makefile
+- tools/vm/config-fragment
+- tools/vm/guest-test.sh
+- tools/vm/run.sh
+homepage: https://github.com/ydah/ublk
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/ydah/ublk
+  source_code_uri: https://github.com/ydah/ublk
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.19
+specification_version: 4
+summary: Write Linux ublk block-device targets in Ruby
+test_files: []