/* SPDX-License-Identifier: LGPL-2.1-or-later */

/*
 * \todo Document the interface and remove the related EXCLUDE_PATTERNS entry.
 */

module ipa.RPi;

import "include/libcamera/ipa/core.mojom";

enum BufferMask {
	MaskID			= 0x00ffff,
	MaskStats		= 0x010000,
	MaskEmbeddedData	= 0x020000,
	MaskBayerData		= 0x040000,
	MaskExternalBuffer	= 0x100000,
};

/* Size of the LS grid allocation. */
const uint32 MaxLsGridSize = 0x8000;

struct SensorConfig {
	uint32 gainDelay;
	uint32 exposureDelay;
	uint32 vblankDelay;
	uint32 sensorMetadata;
};

struct ISPConfig {
	uint32 embeddedBufferId;
	uint32 bayerBufferId;
	bool embeddedBufferPresent;
	libcamera.ControlList controls;
};

struct IPAConfig {
	uint32 transform;
	libcamera.FileDescriptor lsTableHandle;
};

struct StartConfig {
	libcamera.ControlList controls;
	int32 dropFrameCount;
};

interface IPARPiInterface {
	init(libcamera.IPASettings settings)
		=> (int32 ret, SensorConfig sensorConfig);
	start(libcamera.ControlList controls) => (StartConfig startConfig);
	stop();

	/**
	 * \fn configure()
	 * \brief Configure the IPA stream and sensor settings
	 * \param[in] sensorInfo Camera sensor information
	 * \param[in] streamConfig Configuration of all active streams
	 * \param[in] entityControls Controls provided by the pipeline entities
	 * \param[in] ipaConfig Pipeline-handler-specific configuration data
	 * \param[out] controls Controls to apply by the pipeline entity
	 *
	 * This method shall be called when the camera is configured to inform
	 * the IPA of the camera's streams and the sensor settings.
	 *
	 * The \a sensorInfo conveys information about the camera sensor settings that
	 * the pipeline handler has selected for the configuration.
	 *
	 * The \a ipaConfig and \a controls parameters carry data passed by the
	 * pipeline handler to the IPA and back.
	 */
	configure(libcamera.IPACameraSensorInfo sensorInfo,
		  map<uint32, libcamera.IPAStream> streamConfig,
		  map<uint32, libcamera.ControlInfoMap> entityControls,
		  IPAConfig ipaConfig)
		=> (int32 ret, libcamera.ControlList controls);

	/**
	 * \fn mapBuffers()
	 * \brief Map buffers shared between the pipeline handler and the IPA
	 * \param[in] buffers List of buffers to map
	 *
	 * This method informs the IPA module of memory buffers set up by the pipeline
	 * handler that the IPA needs to access. It provides dmabuf file handles for
	 * each buffer, and associates the buffers with unique numerical IDs.
	 *
	 * IPAs shall map the dmabuf file handles to their address space and keep a
	 * cache of the mappings, indexed by the buffer numerical IDs. The IDs are used
	 * in all other IPA interface methods to refer to buffers, including the
	 * unmapBuffers() method.
	 *
	 * All buffers that the pipeline handler wishes to share with an IPA shall be
	 * mapped with this method. Buffers may be mapped all at once with a single
	 * call, or mapped and unmapped dynamically at runtime, depending on the IPA
	 * protocol. Regardless of the protocol, all buffers mapped at a given time
	 * shall have unique numerical IDs.
	 *
	 * The numerical IDs have no meaning defined by the IPA interface, and 
	 * should be treated as opaque handles by IPAs, with the only exception
	 * that ID zero is invalid.
	 *
	 * \sa unmapBuffers()
	 */
	mapBuffers(array<libcamera.IPABuffer> buffers);

	/**
	 * \fn unmapBuffers()
	 * \brief Unmap buffers shared by the pipeline to the IPA
	 * \param[in] ids List of buffer IDs to unmap
	 *
	 * This method removes mappings set up with mapBuffers(). Numerical IDs
	 * of unmapped buffers may be reused when mapping new buffers.
	 *
	 * \sa mapBuffers()
	 */
	unmapBuffers(array<uint32> ids);

	[async] signalStatReady(uint32 bufferId);
	[async] signalQueueRequest(libcamera.ControlList controls);
	[async] signalIspPrepare(ISPConfig data);
};

interface IPARPiEventInterface {
	statsMetadataComplete(uint32 bufferId, libcamera.ControlList controls);
	runIsp(uint32 bufferId);
	embeddedComplete(uint32 bufferId);
	setIspControls(libcamera.ControlList controls);
	setDelayedControls(libcamera.ControlList controls);
};