/**
 * (c) 2026, Micro:bit Educational Foundation and contributors
 *
 * Derived from dapjs (https://github.com/ARMmbed/dapjs) which is
 * Copyright (c) Arm Limited 2018
 * Copyright (c) Microsoft Corporation
 *
 * SPDX-License-Identifier: MIT
 *
 * ARM Debug Interface (ADI) layer for SWD access to a Cortex-M target,
 * derived from dapjs (https://github.com/ARMmbed/dapjs). This file and
 * its siblings (transport.ts, cmsis-dap.ts, cortex-m.ts, daplink.ts)
 * are a minimal reimplementation covering only the features needed for
 * micro:bit.
 *
 * ArmDebugSwd manages the SWD connection lifecycle and provides
 * register-level access to the Debug Port (DP) and Access Port (AP).
 * It sits between CmsisDapUsb (command framing) and higher-level consumers
 * like CortexM (processor control) and DAPLink (flash/serial).
 *
 * Key responsibilities:
 * - SWD initialisation sequence (JTAG-to-SWD switch, power-up, ID read)
 * - Automatic drain-and-retry on stale USB responses after page reload
 * - DP_SELECT and AP_CSW register caching to reduce redundant writes
 * - Memory read/write via AP_TAR + AP_DRW, handling page boundaries
 *   and block-transfer size limits
 *
 * Protocol references:
 * - ARM ADI: https://developer.arm.com/documentation/ihi0031/a/
 * - DAPLink: https://github.com/ARMmbed/DAPLink
 *
 * The dapjs license is included below:
 *
 * DAPjs
 * Copyright (c) Arm Limited 2018
 * Copyright (c) Microsoft Corporation
 *
 * Permission is hereby granted, free of charge, to any person obtaining a copy
 * of this software and associated documentation files (the "Software"), to deal
 * in the Software without restriction, including without limitation the rights
 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 * copies of the Software, and to permit persons to whom the Software is
 * furnished to do so, subject to the following conditions:
 *
 * The above copyright notice and this permission notice shall be included in
 * all copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
 * IN THE SOFTWARE.
 */
import { Logging } from "../logging.js";
import { type CmsisDap, DapOperation } from "./cmsis-dap.js";
export declare function waitFor(fn: () => Promise<boolean>, timeout?: number, delay?: number): Promise<void>;
export interface ArmDebug {
    readonly dap: CmsisDap;
    readonly isOpen: boolean;
    /** Read a 32-bit word from a memory-mapped address. */
    readMem32(address: number): Promise<number>;
    /** Write a 32-bit word to a memory-mapped address. */
    writeMem32(address: number, value: number): Promise<void>;
    /** Build DAP operations for reading a 32-bit word (for use with transferSequence). */
    readMem32Ops(address: number): DapOperation[];
    /** Build DAP operations for writing a 32-bit word (for use with transferSequence). */
    writeMem32Ops(address: number, value: number): DapOperation[];
    /**
     * Read a block of 32-bit words from memory.
     * Handles TAR auto-increment page boundaries and block size limits.
     */
    readBlock(address: number, count: number): Promise<Uint32Array>;
    /**
     * Write a block of 32-bit words to memory.
     * Handles TAR auto-increment page boundaries and block size limits.
     */
    writeBlock(address: number, values: Uint32Array): Promise<void>;
    /**
     * Execute a sequence of operation groups as individual transfers.
     * Each group is sent as a separate DAP_TRANSFER to guarantee that
     * all operations within a group execute atomically on the wire.
     */
    transferSequence(groups: DapOperation[][]): Promise<Uint32Array>;
    /**
     * Reset cached protocol state without closing the transport.
     * Call after operations that reset the target (e.g. DAPLink flash reset).
     */
    resetState(): void;
    /**
     * Connect to the target with automatic drain-and-retry on stale responses.
     */
    connect(maxRetries?: number): Promise<void>;
    disconnect(): Promise<void>;
    /**
     * Reset cached state and reconnect without closing the transport.
     * Use after operations like DAPLink flash that leave the protocol state
     * stale but don't require full re-enumeration.
     */
    reinit(): Promise<void>;
}
export declare class ArmDebugSwd implements ArmDebug {
    readonly dap: CmsisDap;
    private logging;
    private swdConnected;
    private selectedAddress?;
    private cswValue?;
    constructor(dap: CmsisDap, logging: Logging);
    get isOpen(): boolean;
    /**
     * Initialize SWD: connect to the target, set up the debug port,
     * and power up the debug and system domains.
     */
    private connectOnce;
    connect(maxRetries?: number): Promise<void>;
    resetState(): void;
    disconnect(): Promise<void>;
    reinit(): Promise<void>;
    private readDPOps;
    private writeDPOps;
    private readAPOps;
    private writeAPOps;
    readMem32Ops(address: number): DapOperation[];
    writeMem32Ops(address: number, value: number): DapOperation[];
    /**
     * Execute a batch of DAP transfer operations, deduplicating writes
     * to DP_SELECT and AP_CSW that match cached state.
     */
    private transfer;
    transferSequence(groups: DapOperation[][]): Promise<Uint32Array>;
    private readDP;
    readMem32(address: number): Promise<number>;
    writeMem32(address: number, value: number): Promise<void>;
    readBlock(address: number, count: number): Promise<Uint32Array>;
    writeBlock(address: number, values: Uint32Array): Promise<void>;
}