subchannel.cxxm

/// SPDX-License-Identifier: Apache-2.0
/// @file arch/s390x/io/css.cxxm
/// @brief Channel Subsystem core — privileged I/O instruction wrappers and
///        subchannel table management (PoP Chapter 14).
 
export module arch.s390x.io.css.subchannel;
import arch.s390x.io.types;
import zxfoundation.base.types;
import zxfoundation.sync.waitqueue.types;
import lib.error;
import std;
 
export {
 
namespace arch::s390x::io::css {
 
    /// @brief Lifecycle state of a subchannel entry.
    enum class subchannel_state : u8 {
        free    = 0,   ///< Slot is unused.
        probing = 1,   ///< Currently being probed during init.
        idle    = 2,   ///< Probed and enabled, ready for I/O.
        active  = 3,   ///< I/O operation is in progress.
        halting = 4,   ///< Halt or clear has been issued.
    };
 
    /// @brief Kernel I/O completion sink.
    using io_completion_sink_fn = void (*)(
        u32 sch_index, u32 binding_id, u32 binding_generation,
        const irb& status
    ) noexcept;
 
    /// @brief Per-subchannel bookkeeping entry.
    struct subchannel_entry {
        subchannel_id                       schid{};
        senseid_data                        sense{};
        subchannel_state                    state{subchannel_state::free};
        zxfoundation::sync::waitqueue::wait_head io_wait{};
        irb                                 last_irb{};
        std::atomic<u32>                    io_done{0};
        u16                                 devno{0xFFFF};
        u8                                  available_lpm{0};
        u8                                  _pad0[1]{};
        u32                                 binding_id{~0U};
        u32                                 binding_generation{0};
        u32                                 active_binding_id{~0U};
 
        // Non-copyable, non-movable — identity is table slot address.
        subchannel_entry() noexcept = default;
        subchannel_entry(const subchannel_entry&)            = delete;
        subchannel_entry(subchannel_entry&&)                 = delete;
        auto operator=(const subchannel_entry&)              = delete;
        auto operator=(subchannel_entry&&)                   = delete;
    };
 
    /// @brief Probe all subchannels, enable valid ones, and populate the table.
    auto init() noexcept -> void;
 
    /// @brief Start I/O on a subchannel.
    /// @param sch_index Index into the subchannel table.
    /// @param orb_ref   Prepared Operation Request Block.
    /// @return Ok on CC=0; driver_error on failure.
    [[nodiscard]] auto start_io(u32 sch_index, orb& orb_ref) noexcept
        -> ::std::expected<void, ::lib::kernel_error>;
 
    /// @brief Install the nucleus I/O completion sink.
    [[nodiscard]] auto install_completion_sink(
        io_completion_sink_fn sink
    ) noexcept -> ::std::expected<void, ::lib::kernel_error>;
 
    /// @brief Exclusively associate an active I/O binding with a subchannel.
    [[nodiscard]] auto claim_binding(
        u32 sch_index, u32 binding_id, u32 binding_generation
    ) noexcept -> ::std::expected<void, ::lib::kernel_error>;
 
    /// @brief Remove an exact subchannel-binding association after I/O fencing.
    [[nodiscard]] auto release_binding(
        u32 sch_index, u32 binding_id, u32 binding_generation
    ) noexcept -> ::std::expected<void, ::lib::kernel_error>;
 
    /// @brief Return the hardware-available logical path mask for a binding.
    [[nodiscard]] auto available_lpm(u32 sch_index) noexcept -> u8;
 
    /// @brief Test I/O on a subchannel (issue TSCH).
    /// @param sch_index Index into the subchannel table.
    /// @param irb_ref   Output Interruption Response Block.
    /// @return Condition code on success; driver_error on failure.
    [[nodiscard]] auto test_io(u32 sch_index, irb& irb_ref) noexcept
        -> ::std::expected<condition_code, ::lib::kernel_error>;
 
    /// @brief Halt I/O on a subchannel (issue HSCH).
    /// @param sch_index Index into the subchannel table.
    /// @return Ok on CC=0; driver_error on failure.
    [[nodiscard]] auto halt_io(u32 sch_index) noexcept
        -> ::std::expected<void, ::lib::kernel_error>;
 
    /// @brief Clear I/O on a subchannel (issue CSCH).
    /// @param sch_index Index into the subchannel table.
    /// @return Ok on CC=0; driver_error on failure.
    [[nodiscard]] auto clear_io(u32 sch_index) noexcept
        -> ::std::expected<void, ::lib::kernel_error>;
 
    /// @brief Called from the I/O interrupt handler to drain status.
    /// @param sch_no Raw subchannel number from the I/O old PSW area.
    auto io_interrupt(u32 sch_no) noexcept -> void;
 
    /// @brief Find a subchannel by SENSE-ID device type and model.
    /// @param dev_type  Device type from senseid_data.
    /// @param dev_model Device model from senseid_data.
    /// @return Table index on success; not_found error otherwise.
    [[nodiscard]] auto find_device(u16 dev_type, u16 dev_model) noexcept
        -> ::std::expected<u32, ::lib::kernel_error>;
 
    /// @brief Return the number of probed subchannels.
    [[nodiscard]] auto subchannel_count() noexcept -> u32;
 
    /// @brief Return a pointer to a subchannel entry by index.
    /// @param index Index into the subchannel table.
    /// @return Pointer to the entry, or nullptr if index is out of range.
    [[nodiscard]] auto get_entry(u32 index) noexcept -> subchannel_entry*;
 
} // namespace arch::s390x::io::css
 
} // end export