/* SPDX-License-Identifier: GPL-2.0 */
#ifndef GSP_PHYS_BOOTER_H
#define GSP_PHYS_BOOTER_H

#include <linux/types.h>
#include <linux/pci.h>
#include <linux/io.h>

#include "gsp_phys_boot.h"

/*
 * Real-GSP boot stages 3d/3e: Booter Load on SEC2, RISC-V reset and libos
 * arguments, FALCON_OS, RISC-V-active check (3d), then the status-queue poll
 * for the GSP-RM init event (3e).
 *
 * Stage 3d runs only after a successful FWSEC run (WPR2 up) in the same
 * claim. Its host-side staging - FMC copy, radix3 page tables for the GSP-RM
 * ELF, signature copy, message queues and the libos/GSP arguments - runs
 * first; gsp_phys_boot_dryrun prepares exactly that staging with no BAR0
 * writes and no falcon kicks.
 */

bool gsp_phys_boot_enabled(void);
bool gsp_phys_boot_dryrun_enabled(void);

/* True when either boot parameter is set (forces the stage-3b layout). */
bool gsp_phys_boot_requested(void);

/* Views into the staged GSP firmware ELF (set by gsp_phys_gpu.c). */
struct gsp_phys_boot_sources {
	const u8 *fw_image;		/* .fwimage section of the GSP-RM ELF */
	u64 fw_image_size;
	const u8 *fw_signature;		/* .fwsignature_tu10x section */
	u64 fw_signature_size;
};

/*
 * Stage 3d host-memory staging: allocate/copy every sysmem buffer the Booter
 * Load ucode DMAs from, fill the message queues / libos arguments / GSP
 * arguments, update the WPR metadata sysmem addresses and run the placement
 * self-checks. The only device access is the bounded read-only state log.
 * With dryrun=true nothing device-visible is written and no falcon is
 * touched. Staging stays allocated until gsp_phys_boot_quiesce() /
 * gsp_phys_boot_staging_free() on release.
 */
int gsp_phys_boot_prime(struct gsp_phys_boot *boot, struct pci_dev *pdev,
			void __iomem *bar0,
			const struct gsp_phys_boot_sources *src, bool dryrun);

/*
 * Stage 3d device sequence: requires primed staging and WPR2 up. Resets the
 * GSP falcon into RISC-V, programs the libos args mailbox, runs Booter Load
 * on SEC2 with the WPR metadata address, writes FALCON_OS and verifies the
 * RISC-V core is active.
 */
int gsp_phys_boot_run(struct gsp_phys_boot *boot, struct pci_dev *pdev,
		      void __iomem *bar0);

/*
 * Stage 3e: bounded status-queue poll for the GSP-RM init event (function
 * 0x1001, rpc_result 0). When GSP-RM asks the host to execute an inline CPU
 * sequencer command buffer first (function 0x1002,
 * NV_VGPU_MSG_EVENT_GSP_RUN_CPU_SEQUENCER), the buffer is executed against
 * the claimed BAR0 (register operations bounded and validated against
 * bar0_len) and the poll then continues. Non-fatal: a timeout or a sequencer
 * validation/execution failure leaves the successful 3d boot and the release
 * teardown valid.
 */
void gsp_phys_boot_rmwait(struct gsp_phys_boot *boot, void __iomem *bar0,
			  resource_size_t bar0_len);

/*
 * Release sequence, in this order (gsp_phys_gpu_release):
 *   1. gsp_phys_boot_quiesce(): if a Booter Load kick was issued, reset the
 *      GSP falcon (stops RISC-V/GSP-RM) BEFORE the FWSEC teardown runs; no
 *      device access when bar0 is NULL (unresponsive-board abort);
 *   2. the existing gsp_phys_fwsec_release() teardown (FWSEC-SB + booter
 *      unload);
 *   3. gsp_phys_boot_staging_free(): release every host buffer. Called after
 *      both falcons have been reset so no ucode can still DMA from it.
 */
void gsp_phys_boot_quiesce(void __iomem *bar0);
void gsp_phys_boot_staging_free(struct pci_dev *pdev);

#endif /* GSP_PHYS_BOOTER_H */