gxp-host-device-structs.h - kernel/google-modules/gxp/zuma - Git at Google

 /* SPDX-License-Identifier: GPL-2.0 */
 /*
  * GXP host-device interface structures.
  *
  * Copyright (C) 2021 Google LLC
  *
  * This header is shared with the GXP firmware. It establishes the format of the
  * shared structures used by the GXP driver to describe to the GXP FW the HW
  * setup and memory regions needed by the FW to operate.
  * Since the header is shared with the FW, it cannot rely on kernel-specific
  * headers or data structures.
  *
  */

 #ifndef __GXP_HOST_DEVICE_STRUCTURES_H__
 #define __GXP_HOST_DEVICE_STRUCTURES_H__

 #define MAX_NUM_CORES 4

 /* The number of physical doorbells and sync barriers allocated to each VD */
 #define GXP_NUM_DOORBELLS_PER_VD 7
 #define GXP_NUM_SYNC_BARRIERS_PER_VD 4

 /* The first allowed doorbell and sync barrier to be used for VDs' usage */
 #define GXP_DOORBELLS_START 4 /* The first 4 are used for boot */
 #define GXP_SYNC_BARRIERS_START 1 /* The first 1 is used for UART */

 /* Definitions for host->device boot mode requests */
 /*
  * No boot action is needed. This is a valid mode once a core is running.
  * However, it's an invalid state when a FW is powering on. The DSP core will
  * write it to the boot mode register once it starts a transition.
  * This is helpful in case the core reboots/crashes while performing the
  * transition so it doesn't get stuck in a boot loop.
  */
 #define GXP_BOOT_MODE_NONE 0

 /*
  * Request that the core performs a normal cold boot on the next power-on event.
  * This does not actually wake the core up, but is required before powering the
  * core up if cold boot is desired.
  * Core power-on could be performed using any wake-up source like the doorbells.
  * Upon success, the boot status should be GXP_BOOT_STATUS_ACTIVE.
  */
 #define GXP_BOOT_MODE_COLD_BOOT 1

 /*
  * Request that the core suspends on the next suspend signal arrival. This does
  * not trigger a suspend operation. A subsequent mailbox command or notification
  * is needed to trigger the actual transition. Upon success, the boot status
  * should be GXP_BOOT_STATUS_SUSPENDED.
  */
 #define GXP_BOOT_MODE_SUSPEND 2

 /*
  * Request that the core to preempt the active workload on the next suspend
  * signal arrival.Upon success, the boot status should be
  * GXP_BOOT_STATUS_SUSPENDED.
  */
 #define GXP_BOOT_MODE_PREEMPT 3

 /*
  * Request the core resumes on the next power on-event. This does not trigger a
  * resume operation, but is required before powering the core up if warm
  * boot/resume is desired.
  * Core power-on could be performed using any wake-up source like direct LPM
  * transition into PS0. Upon success, the boot status should be
  * GXP_BOOT_STATUS_ACTIVE
  */
 #define GXP_BOOT_MODE_RESUME 4

 /*
  * Request the core shutdown. A subsequent mailbox command or notification
  * is needed to trigger the actual transition. Upon success, the boot status
  * should be GXP_BOOT_STATUS_OFF.
  */
 #define GXP_BOOT_MODE_SHUTDOWN 5

 /* Definitions for host->device boot status */
 /* Initial status */
 #define GXP_BOOT_STATUS_NONE 0

 /* Final status */
 #define GXP_BOOT_STATUS_ACTIVE 1
 #define GXP_BOOT_STATUS_SUSPENDED 2
 #define GXP_BOOT_STATUS_OFF 3

 /* Transition status */
 #define GXP_BOOT_STATUS_INVALID_MODE 4
 #define GXP_BOOT_STATUS_BOOTING 5
 #define GXP_BOOT_STATUS_BOOTING_FAILED 6
 #define GXP_BOOT_STATUS_SUSPENDING 7
 #define GXP_BOOT_STATUS_SUSPENDING_FAILED 8
 #define GXP_BOOT_STATUS_SUSPENDING_FAILED_ACTIVE_WL 9
 #define GXP_BOOT_STATUS_WAITING_FOR_WORKLOAD 10
 #define GXP_BOOT_STATUS_WAITING_FOR_DMA 11
 #define GXP_BOOT_STATUS_SHUTTING_DOWN 12

 /* Bit masks for the status fields in the core telemetry structures. */
 /* The core telemetry buffers have been setup by the host. */
 #define GXP_CORE_TELEMETRY_HOST_STATUS_ENABLED (1 << 0)
 /* The core telemetry buffers are being used by the device. */
 #define GXP_CORE_TELEMETRY_DEVICE_STATUS_ENABLED (1 << 0)
 /* There was an attempt to use the buffers but their content was invalid. */
 #define GXP_CORE_TELEMETRY_DEVICE_STATUS_SANITY_CHECK_FAILED (1 << 1)

 /*
  * A structure describing the core telemetry (logging and tracing) parameters
  * and buffers.
  */
 struct gxp_core_telemetry_descriptor {
 	/* A struct for describing the parameters for core telemetry buffers. */
 	struct core_telemetry_descriptor {
 		/*
 		 * The core telemetry status from the host's point of view. See
 		 * the top of the file for the appropriate flags.
 		 */
 		uint32_t host_status;
 		/*
 		 * The core telemetry status from the device point of view. See
 		 * the top of the file for the appropriate flags.
 		 */
 		uint32_t device_status;
 		/*
 		 * The device address for the buffer used for storing events.
 		 * The head and tail indices are described inside the data
 		 * pointed to by `buffer_addr`.
 		 */
 		uint32_t buffer_addr;
 		/* The size of the buffer (in bytes) */
 		uint32_t buffer_size;
 		/* The watermark interrupt threshold (in bytes) */
 		uint32_t watermark_level;
 	} per_core_loggers[MAX_NUM_CORES], per_core_tracers[MAX_NUM_CORES];
 };

 /*
  * A structure for describing the state of the job this worker core is part of.
  * This struct is expected to change per dispatch/context switch/preepmtion as
  * it describes the HW resources, FW IDs, and other parameters that may change
  * across job dispatches.
  * It also establishes a slot used for the various HW resources this VD is
  * expected to use.
  * Each FW in a VD is expected to be provided its own copy of this structure
  * based on the job that it's part of.
  */
 struct gxp_job_descriptor {
 	/* The number of workers participating in this job. */
 	uint32_t workers_count;

 	/*
 	 * A mapping between a worker ID and the FW ID handling it. The FW ID
 	 * used for handling worker 'w' is defined in worker_to_fw[w].
 	 */
 	int32_t worker_to_fw[MAX_NUM_CORES];

 	/*
 	 * A slot ID between 0 and MAX_NUM_CORES (exclusive) that indicates
 	 * which block of HW resources this VD is expected to use. All system
 	 * HW resources (such as doorbells, sync barriers, etc) are split across
 	 * the slots evenly; usually starting at a specific physical ID and
 	 * spanning a number consecutive instances. The start ID for each HW
 	 * resource category is defined in GXP_<resource_name>_START; and the
 	 * number of resources alloted to each slot is defined in
 	 * GXP_NUM_<resource_name>_PER_VD.
 	 */
 	uint32_t hardware_resources_slot;
 };

 /*
  * A per-FW control structure used to communicate between the host (MCU or
  * kernel) and the DSP core. The region is expected to be hosted in uncached
  * memory.
  */
 struct gxp_host_control_region {
 	/*
 	 * Written to by the FW to indicate to the host that the core is
 	 * alive.
 	 */
 	uint32_t core_alive_magic;

 	/*
 	 * Written to by the FW to indicate to the host that the core can read
 	 * TOP registers.
 	 */
 	uint32_t top_access_ok;

 	/*
 	 * Written to by the host to specify the request FW boot mode. See the
 	 * GXP_BOOT_MODE_* definitions for valid values. Always set by the FW to
 	 * GXP_BOOT_MODE_NONE once the requested boot mode transition is
 	 * completed.
 	 */
 	uint32_t boot_mode;

 	/*
 	 * Written to by the FW to indicate the boot status. See
 	 * GXP_BOOT_STATUS_* definitions for valid values.
 	 */
 	uint32_t boot_status;

 	/* Reserved fields for future expansion */
 	uint32_t reserved_boot[12];

 	/* To be used to communicate statistics for timing events during boot */
 	uint32_t timing_entries[16];

 	/* To be used to communicate crash events in case of failures */
 	uint32_t valid_crash_info;
 	uint32_t crash_exccause;
 	uint32_t crash_excvaddr;
 	uint32_t crash_epc1;
 	uint32_t reserved_crash_info[12];

 	/* Reserved for more categories */
 	uint32_t reserved[16];

 	/*
 	 * The per-core job descriptor. This struct will be inspected by the FW
 	 * at the beginning of every dispatch.
 	 */
 	struct gxp_job_descriptor job_descriptor;
 };

 /*
  * A structure describing the telemetry (logging and tracing) parameters and
  * buffers; this describes R/O aspects of the telemetry buffers.
  */
 struct gxp_telemetry_descriptor_ro {
 	struct telemetry_descriptor_ro {
 		/*
 		 * The telemetry status from the host's point of view. See the
 		 * top of the file for the appropriate flags.
 		 */
 		uint32_t host_status;

 		/*
 		 * The device address for the buffer used for storing events.
 		 * The head and tail indices are described inside the data
 		 * pointed to by `buffer_addr`.
 		 */
 		uint32_t buffer_addr;

 		/* The size of the buffer (in bytes) */
 		uint32_t buffer_size;
 	} per_core_loggers[MAX_NUM_CORES], per_core_tracers[MAX_NUM_CORES];
 };

 /*
  * A structure describing the external state of the VD. This structure is read
  * once by the FW upon the first cold boot and is never checked again.
  */
 struct gxp_vd_descriptor {
 	/* The ID for this GXP application. */
 	uint32_t application_id;

 	/*
 	 * Whether or not this VD has been initialized by one of its cores.
 	 * This variable is protected by sync barrier at offset 0. Should be
 	 * initialized by the host to 0.
 	 */
 	uint32_t vd_is_initialized;
 };

 /*
  * A descriptor for data that is common to the entire system; usually accessed
  * by physical core. This region is mapped as R/O for all VDs. Should be
  * writable by the host (MCU/Kernel)
  */
 struct gxp_system_descriptor_ro {
 	/* A device address for the common debug dump region */
 	uint32_t debug_dump_dev_addr;

 	/*
 	 * A R/O descriptor for the telemetry data. Describing buffer
 	 * parameters.
 	 */
 	struct gxp_telemetry_descriptor_ro telemetry_desc;
 };

 /*
  * A structure describing the telemetry (logging and tracing) parameters; this
  * describes R/W aspects of the telemetry system.
  */
 struct gxp_telemetry_descriptor_rw {
 	/* A struct for describing R/W status parameters of the buffer  */
 	struct telemetry_descriptor_rw {
 		/*
 		 * The telemetry status from the device point of view. See the
 		 * top of the file for the appropriate flags.
 		 */
 		uint32_t device_status;

 		/*
 		 * Whether or not this telemetry category has data available
 		 * for the host
 		 */
 		uint32_t data_available;
 	} per_core_loggers[MAX_NUM_CORES], per_core_tracers[MAX_NUM_CORES];
 };

 /*
  * A descriptor for data that is common to the entire system; usually accessed
  * by physical core. This region is mapped as R/W for all VDs.
  */
 struct gxp_system_descriptor_rw {
 	/* A R/W descriptor for the telemetry data */
 	struct gxp_telemetry_descriptor_rw telemetry_desc;
 };

 #endif /* __GXP_HOST_DEVICE_STRUCTURES_H__ */
	/* SPDX-License-Identifier: GPL-2.0 */
	/*
	* GXP host-device interface structures.
	*
	* Copyright (C) 2021 Google LLC
	*
	* This header is shared with the GXP firmware. It establishes the format of the
	* shared structures used by the GXP driver to describe to the GXP FW the HW
	* setup and memory regions needed by the FW to operate.
	* Since the header is shared with the FW, it cannot rely on kernel-specific
	* headers or data structures.
	*
	*/

	#ifndef __GXP_HOST_DEVICE_STRUCTURES_H__
	#define __GXP_HOST_DEVICE_STRUCTURES_H__

	#define MAX_NUM_CORES 4

	/* The number of physical doorbells and sync barriers allocated to each VD */
	#define GXP_NUM_DOORBELLS_PER_VD 7
	#define GXP_NUM_SYNC_BARRIERS_PER_VD 4

	/* The first allowed doorbell and sync barrier to be used for VDs' usage */
	#define GXP_DOORBELLS_START 4 /* The first 4 are used for boot */
	#define GXP_SYNC_BARRIERS_START 1 /* The first 1 is used for UART */

	/* Definitions for host->device boot mode requests */
	/*
	* No boot action is needed. This is a valid mode once a core is running.
	* However, it's an invalid state when a FW is powering on. The DSP core will
	* write it to the boot mode register once it starts a transition.
	* This is helpful in case the core reboots/crashes while performing the
	* transition so it doesn't get stuck in a boot loop.
	*/
	#define GXP_BOOT_MODE_NONE 0

	/*
	* Request that the core performs a normal cold boot on the next power-on event.
	* This does not actually wake the core up, but is required before powering the
	* core up if cold boot is desired.
	* Core power-on could be performed using any wake-up source like the doorbells.
	* Upon success, the boot status should be GXP_BOOT_STATUS_ACTIVE.
	*/
	#define GXP_BOOT_MODE_COLD_BOOT 1

	/*
	* Request that the core suspends on the next suspend signal arrival. This does
	* not trigger a suspend operation. A subsequent mailbox command or notification
	* is needed to trigger the actual transition. Upon success, the boot status
	* should be GXP_BOOT_STATUS_SUSPENDED.
	*/
	#define GXP_BOOT_MODE_SUSPEND 2

	/*
	* Request that the core to preempt the active workload on the next suspend
	* signal arrival.Upon success, the boot status should be
	* GXP_BOOT_STATUS_SUSPENDED.
	*/
	#define GXP_BOOT_MODE_PREEMPT 3

	/*
	* Request the core resumes on the next power on-event. This does not trigger a
	* resume operation, but is required before powering the core up if warm
	* boot/resume is desired.
	* Core power-on could be performed using any wake-up source like direct LPM
	* transition into PS0. Upon success, the boot status should be
	* GXP_BOOT_STATUS_ACTIVE
	*/
	#define GXP_BOOT_MODE_RESUME 4

	/*
	* Request the core shutdown. A subsequent mailbox command or notification
	* is needed to trigger the actual transition. Upon success, the boot status
	* should be GXP_BOOT_STATUS_OFF.
	*/
	#define GXP_BOOT_MODE_SHUTDOWN 5

	/* Definitions for host->device boot status */
	/* Initial status */
	#define GXP_BOOT_STATUS_NONE 0

	/* Final status */
	#define GXP_BOOT_STATUS_ACTIVE 1
	#define GXP_BOOT_STATUS_SUSPENDED 2
	#define GXP_BOOT_STATUS_OFF 3

	/* Transition status */
	#define GXP_BOOT_STATUS_INVALID_MODE 4
	#define GXP_BOOT_STATUS_BOOTING 5
	#define GXP_BOOT_STATUS_BOOTING_FAILED 6
	#define GXP_BOOT_STATUS_SUSPENDING 7
	#define GXP_BOOT_STATUS_SUSPENDING_FAILED 8
	#define GXP_BOOT_STATUS_SUSPENDING_FAILED_ACTIVE_WL 9
	#define GXP_BOOT_STATUS_WAITING_FOR_WORKLOAD 10
	#define GXP_BOOT_STATUS_WAITING_FOR_DMA 11
	#define GXP_BOOT_STATUS_SHUTTING_DOWN 12

	/* Bit masks for the status fields in the core telemetry structures. */
	/* The core telemetry buffers have been setup by the host. */
	#define GXP_CORE_TELEMETRY_HOST_STATUS_ENABLED (1 << 0)
	/* The core telemetry buffers are being used by the device. */
	#define GXP_CORE_TELEMETRY_DEVICE_STATUS_ENABLED (1 << 0)
	/* There was an attempt to use the buffers but their content was invalid. */
	#define GXP_CORE_TELEMETRY_DEVICE_STATUS_SANITY_CHECK_FAILED (1 << 1)

	/*
	* A structure describing the core telemetry (logging and tracing) parameters
	* and buffers.
	*/
	struct gxp_core_telemetry_descriptor {
	/* A struct for describing the parameters for core telemetry buffers. */
	struct core_telemetry_descriptor {
	/*
	* The core telemetry status from the host's point of view. See
	* the top of the file for the appropriate flags.
	*/
	uint32_t host_status;
	/*
	* The core telemetry status from the device point of view. See
	* the top of the file for the appropriate flags.
	*/
	uint32_t device_status;
	/*
	* The device address for the buffer used for storing events.
	* The head and tail indices are described inside the data
	* pointed to by `buffer_addr`.
	*/
	uint32_t buffer_addr;
	/* The size of the buffer (in bytes) */
	uint32_t buffer_size;
	/* The watermark interrupt threshold (in bytes) */
	uint32_t watermark_level;
	} per_core_loggers[MAX_NUM_CORES], per_core_tracers[MAX_NUM_CORES];
	};

	/*
	* A structure for describing the state of the job this worker core is part of.
	* This struct is expected to change per dispatch/context switch/preepmtion as
	* it describes the HW resources, FW IDs, and other parameters that may change
	* across job dispatches.
	* It also establishes a slot used for the various HW resources this VD is
	* expected to use.
	* Each FW in a VD is expected to be provided its own copy of this structure
	* based on the job that it's part of.
	*/
	struct gxp_job_descriptor {
	/* The number of workers participating in this job. */
	uint32_t workers_count;

	/*
	* A mapping between a worker ID and the FW ID handling it. The FW ID
	* used for handling worker 'w' is defined in worker_to_fw[w].
	*/
	int32_t worker_to_fw[MAX_NUM_CORES];

	/*
	* A slot ID between 0 and MAX_NUM_CORES (exclusive) that indicates
	* which block of HW resources this VD is expected to use. All system
	* HW resources (such as doorbells, sync barriers, etc) are split across
	* the slots evenly; usually starting at a specific physical ID and
	* spanning a number consecutive instances. The start ID for each HW
	* resource category is defined in GXP_<resource_name>_START; and the
	* number of resources alloted to each slot is defined in
	* GXP_NUM_<resource_name>_PER_VD.
	*/
	uint32_t hardware_resources_slot;
	};

	/*
	* A per-FW control structure used to communicate between the host (MCU or
	* kernel) and the DSP core. The region is expected to be hosted in uncached
	* memory.
	*/
	struct gxp_host_control_region {
	/*
	* Written to by the FW to indicate to the host that the core is
	* alive.
	*/
	uint32_t core_alive_magic;

	/*
	* Written to by the FW to indicate to the host that the core can read
	* TOP registers.
	*/
	uint32_t top_access_ok;

	/*
	* Written to by the host to specify the request FW boot mode. See the
	* GXP_BOOT_MODE_* definitions for valid values. Always set by the FW to
	* GXP_BOOT_MODE_NONE once the requested boot mode transition is
	* completed.
	*/
	uint32_t boot_mode;

	/*
	* Written to by the FW to indicate the boot status. See
	* GXP_BOOT_STATUS_* definitions for valid values.
	*/
	uint32_t boot_status;

	/* Reserved fields for future expansion */
	uint32_t reserved_boot[12];

	/* To be used to communicate statistics for timing events during boot */
	uint32_t timing_entries[16];

	/* To be used to communicate crash events in case of failures */
	uint32_t valid_crash_info;
	uint32_t crash_exccause;
	uint32_t crash_excvaddr;
	uint32_t crash_epc1;
	uint32_t reserved_crash_info[12];

	/* Reserved for more categories */
	uint32_t reserved[16];

	/*
	* The per-core job descriptor. This struct will be inspected by the FW
	* at the beginning of every dispatch.
	*/
	struct gxp_job_descriptor job_descriptor;
	};

	/*
	* A structure describing the telemetry (logging and tracing) parameters and
	* buffers; this describes R/O aspects of the telemetry buffers.
	*/
	struct gxp_telemetry_descriptor_ro {
	struct telemetry_descriptor_ro {
	/*
	* The telemetry status from the host's point of view. See the
	* top of the file for the appropriate flags.
	*/
	uint32_t host_status;

	/*
	* The device address for the buffer used for storing events.
	* The head and tail indices are described inside the data
	* pointed to by `buffer_addr`.
	*/
	uint32_t buffer_addr;

	/* The size of the buffer (in bytes) */
	uint32_t buffer_size;
	} per_core_loggers[MAX_NUM_CORES], per_core_tracers[MAX_NUM_CORES];
	};

	/*
	* A structure describing the external state of the VD. This structure is read
	* once by the FW upon the first cold boot and is never checked again.
	*/
	struct gxp_vd_descriptor {
	/* The ID for this GXP application. */
	uint32_t application_id;

	/*
	* Whether or not this VD has been initialized by one of its cores.
	* This variable is protected by sync barrier at offset 0. Should be
	* initialized by the host to 0.
	*/
	uint32_t vd_is_initialized;
	};

	/*
	* A descriptor for data that is common to the entire system; usually accessed
	* by physical core. This region is mapped as R/O for all VDs. Should be
	* writable by the host (MCU/Kernel)
	*/
	struct gxp_system_descriptor_ro {
	/* A device address for the common debug dump region */
	uint32_t debug_dump_dev_addr;

	/*
	* A R/O descriptor for the telemetry data. Describing buffer
	* parameters.
	*/
	struct gxp_telemetry_descriptor_ro telemetry_desc;
	};

	/*
	* A structure describing the telemetry (logging and tracing) parameters; this
	* describes R/W aspects of the telemetry system.
	*/
	struct gxp_telemetry_descriptor_rw {
	/* A struct for describing R/W status parameters of the buffer */
	struct telemetry_descriptor_rw {
	/*
	* The telemetry status from the device point of view. See the
	* top of the file for the appropriate flags.
	*/
	uint32_t device_status;

	/*
	* Whether or not this telemetry category has data available
	* for the host
	*/
	uint32_t data_available;
	} per_core_loggers[MAX_NUM_CORES], per_core_tracers[MAX_NUM_CORES];
	};

	/*
	* A descriptor for data that is common to the entire system; usually accessed
	* by physical core. This region is mapped as R/W for all VDs.
	*/
	struct gxp_system_descriptor_rw {
	/* A R/W descriptor for the telemetry data */
	struct gxp_telemetry_descriptor_rw telemetry_desc;
	};

	#endif /* __GXP_HOST_DEVICE_STRUCTURES_H__ */