Kernel+Services: Enable barebones hot-plug handling capabilities

Userspace initially didn't have any sort of mechanism to handle
device hotplug (either removing or inserting a device).
This meant that after a short term of scanning all known devices, by
fetching device events (DeviceEvent packets) from /dev/devctl, we
basically never try to read it again after SystemServer initialization
code.

To accommodate hotplug needs, we change SystemServer by ensuring it will
generate a known set of device nodes at their location during the its
main initialization code. This includes devices like /dev/mem, /dev/zero
and /dev/full, etc.

The actual responsible userspace program to handle hotplug events is a
new userspace program called DeviceMapper, with following key points:
- Its current task is to to constantly read the /dev/devctl device node.
  Because we already created generic devices, we only handle devices
  that are dynamically-generated in nature, like storage devices, audio
  channels, etc.

- Since dynamically-generated device nodes could have an infinite minor
  numbers, but major numbers are decoded to a device type, we create an
  internal registry based on two structures - DeviceNodeFamily, and
  RegisteredDeviceNode. DeviceNodeFamily objects are attached in the
  main logic code, when handling a DeviceEvent device insertion packet.
  A DeviceNodeFamily object has an internal HashTable to hold objects of
  RegisteredDeviceNode class.

- Because some device nodes could still share the same major number (TTY
  and serial TTY devices), we have two modes of allocation - limited
  allocation (so a range is defined for a major number), or infinite
  range. Therefore, two (or more) separate DeviceNodeFamily objects can
  can exist albeit sharing the same major number, but they are required
  to allocate from a different minor numbers' range to ensure there are
  no collisions.

- As for KCOV, we handle this device differently. In case the user
  compiled the kernel with such support - this happens to be a singular
  device node that we usually don't need, so it's dynamically-generated
  too, and because it has only one instance, we don't register it in our
  internal registry to not make it complicated needlessly.

The Kernel code is modified to allow proper blocking in case of no
events in the DeviceControlDevice class, because otherwise we will need
to poll periodically the device to check if a new event is available,
which would waste CPU time for no good reason.

Userland/Services/DeviceMapper/CMakeLists.txt

@@ -0,0 +1,13 @@
+serenity_component(
+    DeviceMapper
+    REQUIRED
+    TARGETS DeviceMapper
+)
+
+set(SOURCES
+    main.cpp
+    DeviceEventLoop.cpp
+)
+
+serenity_bin(DeviceMapper)
+target_link_libraries(DeviceMapper PRIVATE LibCore LibFileSystem LibMain)

Userland/Services/DeviceMapper/DeviceEventLoop.cpp

@@ -0,0 +1,243 @@
+/*
+ * Copyright (c) 2023, Liav A. <liavalb@hotmail.co.il>
+ *
+ * SPDX-License-Identifier: BSD-2-Clause
+ */
+
+#include "DeviceEventLoop.h"
+#include <AK/Debug.h>
+#include <LibCore/DirIterator.h>
+#include <LibCore/System.h>
+#include <LibIPC/MultiServer.h>
+#include <fcntl.h>
+#include <stdio.h>
+#include <unistd.h>
+
+namespace DeviceMapper {
+
+DeviceEventLoop::DeviceEventLoop(NonnullOwnPtr<Core::File> devctl_file)
+    : m_devctl_file(move(devctl_file))
+{
+}
+
+using MinorNumberAllocationType = DeviceEventLoop::MinorNumberAllocationType;
+
+static constexpr DeviceEventLoop::DeviceNodeMatch s_matchers[] = {
+    { "audio"sv, "audio"sv, "audio/%digit"sv, DeviceNodeFamily::Type::CharacterDevice, 116, MinorNumberAllocationType::SequentialUnlimited, 0, 0, 0220 },
+    { {}, "render"sv, "gpu/render%digit"sv, DeviceNodeFamily::Type::CharacterDevice, 28, MinorNumberAllocationType::SequentialUnlimited, 0, 0, 0666 },
+    { "window"sv, "gpu-connector"sv, "gpu/connector%digit"sv, DeviceNodeFamily::Type::CharacterDevice, 226, MinorNumberAllocationType::SequentialUnlimited, 0, 0, 0660 },
+    { {}, "virtio-console"sv, "hvc0p%digit"sv, DeviceNodeFamily::Type::CharacterDevice, 229, MinorNumberAllocationType::SequentialUnlimited, 0, 0, 0666 },
+    { "phys"sv, "hid-mouse"sv, "input/mouse/%digit"sv, DeviceNodeFamily::Type::CharacterDevice, 10, MinorNumberAllocationType::SequentialUnlimited, 0, 0, 0666 },
+    { "phys"sv, "hid-keyboard"sv, "input/keyboard/%digit"sv, DeviceNodeFamily::Type::CharacterDevice, 85, MinorNumberAllocationType::SequentialUnlimited, 0, 0, 0666 },
+    { {}, "storage"sv, "hd%letter"sv, DeviceNodeFamily::Type::BlockDevice, 3, MinorNumberAllocationType::SequentialUnlimited, 0, 0, 0600 },
+    { "tty"sv, "console"sv, "tty%digit"sv, DeviceNodeFamily::Type::CharacterDevice, 4, MinorNumberAllocationType::SequentialLimited, 0, 63, 0620 },
+    { "tty"sv, "console"sv, "ttyS%digit"sv, DeviceNodeFamily::Type::CharacterDevice, 4, MinorNumberAllocationType::SequentialLimited, 64, 127, 0620 },
+};
+
+static bool is_in_minor_number_range(DeviceEventLoop::DeviceNodeMatch const& matcher, MinorNumber minor_number)
+{
+    if (matcher.minor_number_allocation_type == MinorNumberAllocationType::SequentialUnlimited)
+        return true;
+
+    return matcher.minor_number_start <= minor_number && static_cast<MinorNumber>(matcher.minor_number_start.value() + matcher.minor_number_range_size) >= minor_number;
+}
+
+static Optional<DeviceEventLoop::DeviceNodeMatch const&> device_node_family_to_match_type(DeviceNodeFamily::Type unix_device_type, MajorNumber major_number, MinorNumber minor_number)
+{
+    for (auto& matcher : s_matchers) {
+        if (matcher.major_number == major_number
+            && unix_device_type == matcher.unix_device_type
+            && is_in_minor_number_range(matcher, minor_number))
+            return matcher;
+    }
+    return {};
+}
+
+static bool is_in_family_minor_number_range(DeviceNodeFamily const& family, MinorNumber minor_number)
+{
+    return family.base_minor_number() <= minor_number && static_cast<MinorNumber>(family.base_minor_number().value() + family.devices_symbol_suffix_allocation_map().size()) >= minor_number;
+}
+
+Optional<DeviceNodeFamily&> DeviceEventLoop::find_device_node_family(DeviceNodeFamily::Type unix_device_type, MajorNumber major_number, MinorNumber minor_number) const
+{
+    for (auto const& family : m_device_node_families) {
+        if (family->major_number() == major_number && family->type() == unix_device_type && is_in_family_minor_number_range(*family, minor_number))
+            return *family.ptr();
+    }
+    return {};
+}
+
+ErrorOr<NonnullRefPtr<DeviceNodeFamily>> DeviceEventLoop::find_or_register_new_device_node_family(DeviceNodeMatch const& match, DeviceNodeFamily::Type unix_device_type, MajorNumber major_number, MinorNumber minor_number)
+{
+    if (auto possible_family = find_device_node_family(unix_device_type, major_number, minor_number); possible_family.has_value())
+        return possible_family.release_value();
+    unsigned allocation_map_size = 1024;
+    if (match.minor_number_allocation_type == MinorNumberAllocationType::SequentialLimited)
+        allocation_map_size = match.minor_number_range_size;
+    auto bitmap = TRY(Bitmap::create(allocation_map_size, false));
+    auto node = TRY(adopt_nonnull_ref_or_enomem(new (nothrow) DeviceNodeFamily(move(bitmap),
+        match.family_type_literal,
+        unix_device_type,
+        major_number,
+        minor_number)));
+    TRY(m_device_node_families.try_append(node));
+
+    return node;
+}
+
+static ErrorOr<String> build_suffix_with_letters(size_t allocation_index)
+{
+    auto base_string = TRY(String::from_utf8(""sv));
+    while (true) {
+        base_string = TRY(String::formatted("{:c}{}", 'a' + (allocation_index % 26), base_string));
+        allocation_index = (allocation_index / 26);
+        if (allocation_index == 0)
+            break;
+        allocation_index = allocation_index - 1;
+    }
+    return base_string;
+}
+
+static ErrorOr<String> build_suffix_with_numbers(size_t allocation_index)
+{
+    return String::number(allocation_index);
+}
+
+static ErrorOr<void> prepare_permissions_after_populating_devtmpfs(StringView path, DeviceEventLoop::DeviceNodeMatch const& match)
+{
+    if (match.permission_group.is_null())
+        return {};
+    auto group = TRY(Core::System::getgrnam(match.permission_group));
+    VERIFY(group.has_value());
+    TRY(Core::System::endgrent());
+    TRY(Core::System::chown(path, 0, group.value().gr_gid));
+    return {};
+}
+
+ErrorOr<void> DeviceEventLoop::register_new_device(DeviceNodeFamily::Type unix_device_type, MajorNumber major_number, MinorNumber minor_number)
+{
+    auto possible_match = device_node_family_to_match_type(unix_device_type, major_number, minor_number);
+    if (!possible_match.has_value())
+        return {};
+    auto const& match = possible_match.release_value();
+    auto device_node_family = TRY(find_or_register_new_device_node_family(match, unix_device_type, major_number, minor_number));
+    static constexpr StringView devtmpfs_base_path = "/dev/"sv;
+    auto path_pattern = TRY(String::from_utf8(match.path_pattern));
+    auto& allocation_map = device_node_family->devices_symbol_suffix_allocation_map();
+    auto possible_allocated_suffix_index = allocation_map.find_first_unset();
+    if (!possible_allocated_suffix_index.has_value()) {
+        // FIXME: Make the allocation map bigger?
+        return Error::from_errno(ERANGE);
+    }
+    auto allocated_suffix_index = possible_allocated_suffix_index.release_value();
+
+    auto path = TRY(String::from_utf8(path_pattern));
+    if (match.path_pattern.contains("%digit"sv)) {
+        auto replacement = TRY(build_suffix_with_numbers(allocated_suffix_index));
+        path = TRY(path.replace("%digit"sv, replacement, ReplaceMode::All));
+    }
+    if (match.path_pattern.contains("%letter"sv)) {
+        auto replacement = TRY(build_suffix_with_letters(allocated_suffix_index));
+        path = TRY(path.replace("%letter"sv, replacement, ReplaceMode::All));
+    }
+    VERIFY(!path.is_empty());
+    path = TRY(String::formatted("{}{}", devtmpfs_base_path, path));
+    mode_t old_mask = umask(0);
+    if (unix_device_type == DeviceNodeFamily::Type::BlockDevice)
+        TRY(Core::System::create_block_device(path.bytes_as_string_view(), match.create_mode, major_number.value(), minor_number.value()));
+    else
+        TRY(Core::System::create_char_device(path.bytes_as_string_view(), match.create_mode, major_number.value(), minor_number.value()));
+    umask(old_mask);
+    TRY(prepare_permissions_after_populating_devtmpfs(path.bytes_as_string_view(), match));
+
+    auto result = TRY(device_node_family->registered_nodes().try_set(RegisteredDeviceNode { move(path), minor_number }, AK::HashSetExistingEntryBehavior::Keep));
+    VERIFY(result != HashSetResult::ReplacedExistingEntry);
+    if (result == HashSetResult::KeptExistingEntry) {
+        // FIXME: Handle this case properly.
+        return Error::from_errno(EEXIST);
+    }
+    allocation_map.set(allocated_suffix_index, true);
+    return {};
+}
+
+ErrorOr<void> DeviceEventLoop::unregister_device(DeviceNodeFamily::Type unix_device_type, MajorNumber major_number, MinorNumber minor_number)
+{
+    if (!device_node_family_to_match_type(unix_device_type, major_number, minor_number).has_value())
+        return {};
+    auto possible_family = find_device_node_family(unix_device_type, major_number, minor_number);
+    if (!possible_family.has_value()) {
+        // FIXME: Handle cases where we can't remove a device node.
+        // This could happen when the DeviceMapper program was restarted
+        // so the previous state was not preserved and a device was removed.
+        return Error::from_errno(ENODEV);
+    }
+    auto& family = possible_family.release_value();
+    for (auto& node : family.registered_nodes()) {
+        if (node.minor_number() == minor_number)
+            TRY(Core::System::unlink(node.device_path()));
+    }
+    auto removed_anything = family.registered_nodes().remove_all_matching([minor_number](auto& device) { return device.minor_number() == minor_number; });
+    if (!removed_anything) {
+        // FIXME: Handle cases where we can't remove a device node.
+        // This could happen when the DeviceMapper program was restarted
+        // so the previous state was not preserved and a device was removed.
+        return Error::from_errno(ENODEV);
+    }
+    return {};
+}
+
+static ErrorOr<void> create_kcov_device_node()
+{
+    mode_t old_mask = umask(0);
+    ScopeGuard umask_guard([old_mask] { umask(old_mask); });
+    TRY(Core::System::create_char_device("/dev/kcov"sv, 0666, 30, 0));
+    return {};
+}
+
+ErrorOr<void> DeviceEventLoop::read_one_or_eof(DeviceEvent& event)
+{
+    if (m_devctl_file->read_until_filled({ bit_cast<u8*>(&event), sizeof(DeviceEvent) }).is_error()) {
+        // Bad! Kernel and SystemServer apparently disagree on the record size,
+        // which means that previous data is likely to be invalid.
+        return Error::from_string_view("File ended after incomplete record? /dev/devctl seems broken!"sv);
+    }
+    return {};
+}
+
+ErrorOr<void> DeviceEventLoop::drain_events_from_devctl()
+{
+    for (;;) {
+        DeviceEvent event;
+        TRY(read_one_or_eof(event));
+        // NOTE: Ignore any event related to /dev/devctl device node - normally
+        // it should never disappear from the system and we already use it in this
+        // code.
+        if (event.major_number == 2 && event.minor_number == 10 && !event.is_block_device)
+            continue;
+
+        if (event.state == DeviceEvent::State::Inserted) {
+            // NOTE: We have a special function for the KCOV device, because we don't
+            // want to create a new MinorNumberAllocationType (e.g. SingleInstance).
+            // Instead, just blindly create that device node and assume we will never
+            // have to worry about it, so we don't need to register that!
+            if (event.major_number == 30 && event.minor_number == 0 && !event.is_block_device) {
+                TRY(create_kcov_device_node());
+                continue;
+            }
+            VERIFY(event.is_block_device == 1 || event.is_block_device == 0);
+            TRY(register_new_device(event.is_block_device ? DeviceNodeFamily::Type::BlockDevice : DeviceNodeFamily::Type::CharacterDevice, event.major_number, event.minor_number));
+        } else if (event.state == DeviceEvent::State::Removed) {
+            if (event.major_number == 30 && event.minor_number == 0 && !event.is_block_device) {
+                dbgln("DeviceMapper: unregistering device failed: kcov tried to de-register itself!?");
+                continue;
+            }
+            if (auto error_or_void = unregister_device(event.is_block_device ? DeviceNodeFamily::Type::BlockDevice : DeviceNodeFamily::Type::CharacterDevice, event.major_number, event.minor_number); error_or_void.is_error())
+                dbgln("DeviceMapper: unregistering device failed: {}", error_or_void.error());
+        } else {
+            dbgln("DeviceMapper: Unhandled device event ({:x})!", event.state);
+        }
+    }
+    VERIFY_NOT_REACHED();
+}
+
+}

Userland/Services/DeviceMapper/DeviceEventLoop.h

@@ -0,0 +1,61 @@
+/*
+ * Copyright (c) 2023, Liav A. <liavalb@hotmail.co.il>
+ *
+ * SPDX-License-Identifier: BSD-2-Clause
+ */
+
+#pragma once
+
+#include "DeviceNodeFamily.h"
+#include <AK/ByteBuffer.h>
+#include <Kernel/API/DeviceEvent.h>
+#include <Kernel/API/DeviceFileTypes.h>
+#include <LibCore/EventLoop.h>
+#include <LibCore/File.h>
+#include <LibCore/Notifier.h>
+
+namespace DeviceMapper {
+
+class DeviceEventLoop {
+public:
+    enum class MinorNumberAllocationType {
+        SequentialUnlimited,
+        SequentialLimited,
+    };
+
+    enum class UnixDeviceType {
+        BlockDevice,
+        CharacterDevice,
+    };
+
+    struct DeviceNodeMatch {
+        StringView permission_group;
+        StringView family_type_literal;
+        StringView path_pattern;
+        DeviceNodeFamily::Type unix_device_type;
+        MajorNumber major_number;
+        MinorNumberAllocationType minor_number_allocation_type;
+        MinorNumber minor_number_start;
+        size_t minor_number_range_size;
+        mode_t create_mode;
+    };
+
+    DeviceEventLoop(NonnullOwnPtr<Core::File>);
+    virtual ~DeviceEventLoop() = default;
+
+    ErrorOr<void> drain_events_from_devctl();
+
+private:
+    Optional<DeviceNodeFamily&> find_device_node_family(DeviceNodeFamily::Type unix_device_type, MajorNumber major_number, MinorNumber minor_number) const;
+    ErrorOr<NonnullRefPtr<DeviceNodeFamily>> find_or_register_new_device_node_family(DeviceNodeMatch const& match, DeviceNodeFamily::Type unix_device_type, MajorNumber major_number, MinorNumber minor_number);
+
+    ErrorOr<void> register_new_device(DeviceNodeFamily::Type unix_device_type, MajorNumber major_number, MinorNumber minor_number);
+    ErrorOr<void> unregister_device(DeviceNodeFamily::Type unix_device_type, MajorNumber major_number, MinorNumber minor_number);
+
+    ErrorOr<void> read_one_or_eof(DeviceEvent& event);
+
+    Vector<NonnullRefPtr<DeviceNodeFamily>> m_device_node_families;
+    NonnullOwnPtr<Core::File> const m_devctl_file;
+};
+
+}

Userland/Services/DeviceMapper/DeviceNodeFamily.h

@@ -0,0 +1,52 @@
+/*
+ * Copyright (c) 2023, Liav A. <liavalb@hotmail.co.il>
+ *
+ * SPDX-License-Identifier: BSD-2-Clause
+ */
+
+#pragma once
+
+#include "RegisteredDeviceNode.h"
+#include <AK/Bitmap.h>
+#include <AK/HashTable.h>
+#include <AK/Types.h>
+#include <Kernel/API/DeviceFileTypes.h>
+
+namespace DeviceMapper {
+
+class DeviceNodeFamily : public RefCounted<DeviceNodeFamily> {
+public:
+    enum class Type {
+        BlockDevice,
+        CharacterDevice,
+    };
+
+    DeviceNodeFamily(Bitmap devices_symbol_suffix_allocation_map, StringView literal_device_family, Type type, MajorNumber major, MinorNumber base_minor)
+        : m_literal_device_family(literal_device_family)
+        , m_type(type)
+        , m_major(major)
+        , m_base_minor(base_minor)
+        , m_devices_symbol_suffix_allocation_map(move(devices_symbol_suffix_allocation_map))
+    {
+    }
+
+    StringView literal_device_family() const { return m_literal_device_family; }
+    MajorNumber major_number() const { return m_major; }
+    MinorNumber base_minor_number() const { return m_base_minor; }
+    Type type() const { return m_type; }
+
+    HashTable<RegisteredDeviceNode>& registered_nodes() { return m_registered_nodes; }
+    Bitmap& devices_symbol_suffix_allocation_map() { return m_devices_symbol_suffix_allocation_map; }
+    Bitmap const& devices_symbol_suffix_allocation_map() const { return m_devices_symbol_suffix_allocation_map; }
+
+private:
+    StringView m_literal_device_family;
+    Type m_type { Type::CharacterDevice };
+    MajorNumber m_major { 0 };
+    MinorNumber m_base_minor { 0 };
+
+    HashTable<RegisteredDeviceNode> m_registered_nodes;
+    Bitmap m_devices_symbol_suffix_allocation_map;
+};
+
+}

Userland/Services/DeviceMapper/RegisteredDeviceNode.h

@@ -0,0 +1,49 @@
+/*
+ * Copyright (c) 2023, Liav A. <liavalb@hotmail.co.il>
+ *
+ * SPDX-License-Identifier: BSD-2-Clause
+ */
+
+#pragma once
+
+#include <AK/Bitmap.h>
+#include <AK/String.h>
+#include <AK/Types.h>
+#include <Kernel/API/DeviceFileTypes.h>
+
+namespace DeviceMapper {
+
+class RegisteredDeviceNode {
+public:
+    RegisteredDeviceNode(String device_path, MinorNumber minor)
+        : m_device_path(move(device_path))
+        , m_minor(minor)
+    {
+    }
+
+    StringView device_path() const { return m_device_path.bytes_as_string_view(); }
+    MinorNumber minor_number() const { return m_minor; }
+
+private:
+    String m_device_path;
+    MinorNumber m_minor { 0 };
+};
+
+}
+
+namespace AK {
+
+template<>
+struct Traits<DeviceMapper::RegisteredDeviceNode> : public GenericTraits<DeviceMapper::RegisteredDeviceNode> {
+    static unsigned hash(DeviceMapper::RegisteredDeviceNode const& node)
+    {
+        return int_hash(node.minor_number().value());
+    }
+
+    static bool equals(DeviceMapper::RegisteredDeviceNode const& a, DeviceMapper::RegisteredDeviceNode const& b)
+    {
+        return a.minor_number() == b.minor_number();
+    }
+};
+
+}

Userland/Services/DeviceMapper/main.cpp

@@ -0,0 +1,49 @@
+/*
+ * Copyright (c) 2023, Liav A. <liavalb@hotmail.co.il>
+ *
+ * SPDX-License-Identifier: BSD-2-Clause
+ */
+
+#include "DeviceEventLoop.h"
+#include <AK/Assertions.h>
+#include <AK/ByteBuffer.h>
+#include <AK/Debug.h>
+#include <AK/String.h>
+#include <Kernel/API/DeviceEvent.h>
+#include <LibCore/ArgsParser.h>
+#include <LibCore/ConfigFile.h>
+#include <LibCore/DirIterator.h>
+#include <LibCore/Event.h>
+#include <LibCore/EventLoop.h>
+#include <LibCore/File.h>
+#include <LibCore/System.h>
+#include <LibMain/Main.h>
+#include <errno.h>
+#include <fcntl.h>
+#include <grp.h>
+#include <stdio.h>
+#include <sys/stat.h>
+#include <sys/sysmacros.h>
+#include <sys/types.h>
+#include <unistd.h>
+
+ErrorOr<int> serenity_main(Main::Arguments)
+{
+    TRY(Core::System::unveil("/dev/"sv, "rwc"sv));
+    TRY(Core::System::unveil("/etc/group"sv, "rw"sv));
+    TRY(Core::System::unveil(nullptr, nullptr));
+    TRY(Core::System::pledge("stdio rpath dpath wpath cpath chown fattr"));
+
+    auto file_or_error = Core::File::open("/dev/devctl"sv, Core::File::OpenMode::Read);
+    if (file_or_error.is_error()) {
+        warnln("Failed to open /dev/devctl - {}", file_or_error.error());
+        VERIFY_NOT_REACHED();
+    }
+    auto file = file_or_error.release_value();
+    DeviceMapper::DeviceEventLoop device_event_loop(move(file));
+    if (auto result = device_event_loop.drain_events_from_devctl(); result.is_error())
+        dbgln("DeviceMapper: Fatal error: {}", result.release_error());
+    // NOTE: If we return from drain_events_from_devctl, it must be an error
+    // so we should always return 1!
+    return 1;
+}