gxp-host-device-structs.h - kernel/google-modules/gxp/gs201 - Gitiles

 /* 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
 #define NUM_SYSTEM_SEMAPHORES 64

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

 /* Definitions for host->device boot mode requests */
 /*
  * Request that the core performs a normal cold boot on the next power-on event.
  * This does not actually wake the core up, but's 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.
  */
 #define GXP_BOOT_MODE_REQUEST_COLD_BOOT                 0

 /*
  * 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.
  */
 #define GXP_BOOT_MODE_REQUEST_SUSPEND                   1

 /*
  * Request the core resumes on the next power on-event. This does not trigger a
  * resume operation, but's 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.
  */
 #define GXP_BOOT_MODE_REQUEST_RESUME                    2

 /* Cold boot status definitions */
 #define GXP_BOOT_MODE_STATUS_COLD_BOOT_PENDING          0
 #define GXP_BOOT_MODE_STATUS_COLD_BOOT_COMPLETED        3

 /* Core suspend status definitions */
 #define GXP_BOOT_MODE_STATUS_SUSPEND_PENDING            1
 #define GXP_BOOT_MODE_STATUS_SUSPEND_STARTED            4
 #define GXP_BOOT_MODE_STATUS_SUSPEND_COMPLETED          5
 #define GXP_BOOT_MODE_STATUS_SUSPEND_ABORTED            6

 /* Core resume/warm boot status definitions */
 #define GXP_BOOT_MODE_STATUS_RESUME_PENDING             2
 #define GXP_BOOT_MODE_STATUS_RESUME_STARTED             7
 #define GXP_BOOT_MODE_STATUS_RESUME_COMPLETED           8
 #define GXP_BOOT_MODE_STATUS_RESUME_FAILED              9

 /* Invalid boot mode request code */
 #define GXP_BOOT_MODE_STATUS_INVALID_MODE               10

 /* A structure describing the state of the doorbells on the system. */
 struct gxp_doorbells_descriptor {
 	/* The app this descriptor belongs to. */
 	uint32_t application_id;
 	/* The physical ID of the sync barrier protecting this region. */
 	uint32_t protection_barrier;
 	/* The number of doorbells described in this region. */
 	uint32_t num_items;
 	/* The list of doorbells available for usage. */
 	struct dooorbell_metadata_t {
 		/*
 		 * The number of users using this doorbell. 0 when it's
 		 * available.
 		 */
 		uint32_t users_count;
 		/* The 0-based index of the doorbell described by this entry. */
 		uint32_t hw_doorbell_idx;
 	} doorbells[];
 };

 /* A structure describing the state of the sync barriers on the system. */
 struct gxp_sync_barriers_descriptor {
 	/* The app this descriptor belongs to. */
 	uint32_t application_id;
 	/* The physical ID of the sync barrier protecting this region. */
 	uint32_t protection_barrier;
 	/* The number of sync barriers described in this region. */
 	uint32_t num_items;
 	/* The list of sync barriers available for usage. */
 	struct sync_barrier_metadata_t {
 		/*
 		 * The number of users using this barrier. 0 when it's
 		 * available.
 		 */
 		uint32_t users_count;
 		/*
 		 * The 0-based index of the sync barrier described by this
 		 * entry.
 		 */
 		uint32_t hw_barrier_idx;
 	} barriers[];
 };

 /* A structure describing the state of the watchdog on the system. */
 struct gxp_watchdog_descriptor {
 	/* The physical ID of the sync barrier protecting this region. */
 	uint32_t protection_barrier;
 	/*
 	 * The number of timer ticks before the watchdog expires.
 	 * This is in units of 244.14 ns.
 	 */
 	uint32_t target_value;
 	/* A bit mask of the cores expected to tickle the watchdog. */
 	uint32_t participating_cores;
 	/* A bit mask of the cores that have tickled the watchdog. */
 	uint32_t responded_cores;
 	/* A flag indicating whether or not the watchdog has tripped. */
 	uint32_t tripped;
 };

 /*
  * A structure describing the telemetry (logging and tracing) parameters and
  * buffers.
  */
 struct gxp_telemetry_descriptor {
 	/* A struct for describing the parameters for telemetry buffers  */
 	struct telemetry_descriptor {
 		/*
 		 * 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 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 describing the state and allocations of the SW-based semaphores
  * on the system.
  */
 struct gxp_semaphores_descriptor {
 	/* The app this descriptor belongs to. */
 	uint32_t application_id;
 	/* The physical ID of the sync barrier protecting this region. */
 	uint32_t protection_barrier;
 	/*
 	 * An array where each element is dedicated to a core. The element is a
 	 * bit map describing of all the semaphores in the list below that have
 	 * been unlocked but haven't been processed yet by the receiptient core.
 	 */
 	uint64_t woken_pending_semaphores[MAX_NUM_CORES];
 	/*
 	 * A mapping of which doorbells to use as a wakeup signal source per
 	 * core.
 	 */
 	uint32_t wakeup_doorbells[MAX_NUM_CORES];
 	/* The number of items described in this region. */
 	uint32_t num_items;
 	/* The list of semaphores available for usage. */
 	struct semaphore_metadata {
 		/*
 		 * The number of users using this semaphore. 0 when it's for
 		 * creation.
 		 * Note: this is not the count value of the semaphore, but just
 		 * an indication if this slot is available.
 		 */
 		uint32_t users_count;
 		/*
 		 * This is the semaphore count. Cores will block when they call
 		 * 'Wait()' while this count is 0.
 		 */
 		uint32_t count;
 		/*
 		 * A bit map of 'NUM_DSP_CORES' bits indicating which cores are
 		 * currently waiting on this semaphore to become available.
 		 */
 		uint32_t waiters;
 	} semaphores[NUM_SYSTEM_SEMAPHORES];
 };

 /* A basic unidirectional queue. */
 struct gxp_queue_info {
 	/* A header describing the queue and its state. */
 	struct queue_header {
 		/* A device-side pointer of the storage managed by this queue */
 		uint32_t storage;
 		/* The index to the head of the queue. */
 		uint32_t head_idx;
 		/* The index to the tail of the queue. */
 		uint32_t tail_idx;
 		/* The size of an element stored this queue. */
 		uint32_t element_size;
 		/* The number of elements that can be stored in this queue. */
 		uint32_t elements_count;
 	} header;
 	/* The semaphore ID controlling exclusive access to this core. */
 	uint32_t access_sem_id;
 	/*
 	 * The ID for the semaphore containing the number of unprocessed items
 	 * pushed to this queue.
 	 */
 	uint32_t posted_slots_sem_id;
 	/*
 	 * The ID for the semaphore containing the number of free slots
 	 * available to store data in this queue.
 	 */
 	uint32_t free_slots_sem_id;
 };

 /* A struct describing a single core's set of incoming queues. */
 struct gxp_core_info {
 	/*
 	 * The metadata for the queue holding incoming commands from other
 	 * cores.
 	 */
 	struct gxp_queue_info incoming_commands_queue;
 	/*
 	 * The metadata for the queue holding incoming responses from other
 	 * cores.
 	 */
 	struct gxp_queue_info incoming_responses_queue;
 };

 /* A structure describing all the cores' per-core metadata. */
 struct gxp_cores_descriptor {
 	/* The number of cores described in this descriptor. */
 	uint32_t num_items;
 	/* The descriptors for each core. */
 	struct gxp_core_info cores[];
 };

 /*
  * The top level descriptor describing memory regions used to access system-wide
  * structures and resources.
  */
 struct gxp_system_descriptor {
 	/* A device address for the application data descriptor. */
 	uint32_t app_descriptor_dev_addr[MAX_NUM_CORES];
 	/* A device address for the watchdog descriptor. */
 	uint32_t watchdog_dev_addr;
 	/* A device address for the telemetry descriptor */
 	uint32_t telemetry_dev_addr;
 	/* A device address for the common debug dump region */
 	uint32_t debug_dump_dev_addr;
 };

 /* A structure describing the metadata belonging to a specific application. */
 struct gxp_application_descriptor {
 	/* The ID for this GXP application. */
 	uint32_t application_id;
 	/* The number of cores this application has. */
 	uint16_t core_count;
 	/*
 	 * The cores mask; a bit at index `n` indicates that core `n` is part of
 	 * this app.
 	 */
 	uint16_t cores_mask;
 	/* The number of threads allocated for each core. */
 	uint16_t threads_count;
 	/* The size of system memory given to this app. */
 	uint32_t system_memory_size;
 	/* The device-address of the system memory given to this app. */
 	uint32_t system_memory_addr;
 	/* The size of TCM memory allocated per bank for this app. */
 	uint32_t tcm_memory_per_bank;   /* in units of 4 kB */
 	/* A device address for the doorbells descriptor. */
 	uint32_t doorbells_dev_addr;
 	/* A device address for the sync barriers descriptor. */
 	uint32_t sync_barriers_dev_addr;
 	/* A device address for the semaphores descriptor. */
 	uint32_t semaphores_dev_addr;
 	/* A device address for the cores cmd/rsp queues descriptor. */
 	uint32_t cores_info_dev_addr;
 };

 /* The structure describing a core-to-core command. */
 struct gxp_core_to_core_command {
 	/* The source of port number (the core's virtual ID) of the command. */
 	uint32_t source;
 	/* The command's sequence number. */
 	uint64_t sequence_number;
 	/* The command payload device address. */
 	uint64_t device_address;
 	/* The size of the payload in bytes. */
 	uint32_t size;
 	/* The generic command flags. */
 	uint32_t flags;
 };

 /* The structure describing a core-to-core response. */
 struct gxp_core_to_core_response {
 	/* The source of port number (the core's virtual ID) of the response. */
 	uint32_t source;
 	/* The response's sequence number. */
 	uint64_t sequence_number;
 	/* The response error code (if any). */
 	uint16_t error_code;
 	/* The response return value (filled-in by the user). */
 	int32_t cmd_retval;
 };

 #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
	#define NUM_SYSTEM_SEMAPHORES 64

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

	/* Definitions for host->device boot mode requests */
	/*
	* Request that the core performs a normal cold boot on the next power-on event.
	* This does not actually wake the core up, but's 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.
	*/
	#define GXP_BOOT_MODE_REQUEST_COLD_BOOT 0

	/*
	* 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.
	*/
	#define GXP_BOOT_MODE_REQUEST_SUSPEND 1

	/*
	* Request the core resumes on the next power on-event. This does not trigger a
	* resume operation, but's 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.
	*/
	#define GXP_BOOT_MODE_REQUEST_RESUME 2

	/* Cold boot status definitions */
	#define GXP_BOOT_MODE_STATUS_COLD_BOOT_PENDING 0
	#define GXP_BOOT_MODE_STATUS_COLD_BOOT_COMPLETED 3

	/* Core suspend status definitions */
	#define GXP_BOOT_MODE_STATUS_SUSPEND_PENDING 1
	#define GXP_BOOT_MODE_STATUS_SUSPEND_STARTED 4
	#define GXP_BOOT_MODE_STATUS_SUSPEND_COMPLETED 5
	#define GXP_BOOT_MODE_STATUS_SUSPEND_ABORTED 6

	/* Core resume/warm boot status definitions */
	#define GXP_BOOT_MODE_STATUS_RESUME_PENDING 2
	#define GXP_BOOT_MODE_STATUS_RESUME_STARTED 7
	#define GXP_BOOT_MODE_STATUS_RESUME_COMPLETED 8
	#define GXP_BOOT_MODE_STATUS_RESUME_FAILED 9

	/* Invalid boot mode request code */
	#define GXP_BOOT_MODE_STATUS_INVALID_MODE 10

	/* A structure describing the state of the doorbells on the system. */
	struct gxp_doorbells_descriptor {
	/* The app this descriptor belongs to. */
	uint32_t application_id;
	/* The physical ID of the sync barrier protecting this region. */
	uint32_t protection_barrier;
	/* The number of doorbells described in this region. */
	uint32_t num_items;
	/* The list of doorbells available for usage. */
	struct dooorbell_metadata_t {
	/*
	* The number of users using this doorbell. 0 when it's
	* available.
	*/
	uint32_t users_count;
	/* The 0-based index of the doorbell described by this entry. */
	uint32_t hw_doorbell_idx;
	} doorbells[];
	};

	/* A structure describing the state of the sync barriers on the system. */
	struct gxp_sync_barriers_descriptor {
	/* The app this descriptor belongs to. */
	uint32_t application_id;
	/* The physical ID of the sync barrier protecting this region. */
	uint32_t protection_barrier;
	/* The number of sync barriers described in this region. */
	uint32_t num_items;
	/* The list of sync barriers available for usage. */
	struct sync_barrier_metadata_t {
	/*
	* The number of users using this barrier. 0 when it's
	* available.
	*/
	uint32_t users_count;
	/*
	* The 0-based index of the sync barrier described by this
	* entry.
	*/
	uint32_t hw_barrier_idx;
	} barriers[];
	};

	/* A structure describing the state of the watchdog on the system. */
	struct gxp_watchdog_descriptor {
	/* The physical ID of the sync barrier protecting this region. */
	uint32_t protection_barrier;
	/*
	* The number of timer ticks before the watchdog expires.
	* This is in units of 244.14 ns.
	*/
	uint32_t target_value;
	/* A bit mask of the cores expected to tickle the watchdog. */
	uint32_t participating_cores;
	/* A bit mask of the cores that have tickled the watchdog. */
	uint32_t responded_cores;
	/* A flag indicating whether or not the watchdog has tripped. */
	uint32_t tripped;
	};

	/*
	* A structure describing the telemetry (logging and tracing) parameters and
	* buffers.
	*/
	struct gxp_telemetry_descriptor {
	/* A struct for describing the parameters for telemetry buffers */
	struct telemetry_descriptor {
	/*
	* 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 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 describing the state and allocations of the SW-based semaphores
	* on the system.
	*/
	struct gxp_semaphores_descriptor {
	/* The app this descriptor belongs to. */
	uint32_t application_id;
	/* The physical ID of the sync barrier protecting this region. */
	uint32_t protection_barrier;
	/*
	* An array where each element is dedicated to a core. The element is a
	* bit map describing of all the semaphores in the list below that have
	* been unlocked but haven't been processed yet by the receiptient core.
	*/
	uint64_t woken_pending_semaphores[MAX_NUM_CORES];
	/*
	* A mapping of which doorbells to use as a wakeup signal source per
	* core.
	*/
	uint32_t wakeup_doorbells[MAX_NUM_CORES];
	/* The number of items described in this region. */
	uint32_t num_items;
	/* The list of semaphores available for usage. */
	struct semaphore_metadata {
	/*
	* The number of users using this semaphore. 0 when it's for
	* creation.
	* Note: this is not the count value of the semaphore, but just
	* an indication if this slot is available.
	*/
	uint32_t users_count;
	/*
	* This is the semaphore count. Cores will block when they call
	* 'Wait()' while this count is 0.
	*/
	uint32_t count;
	/*
	* A bit map of 'NUM_DSP_CORES' bits indicating which cores are
	* currently waiting on this semaphore to become available.
	*/
	uint32_t waiters;
	} semaphores[NUM_SYSTEM_SEMAPHORES];
	};

	/* A basic unidirectional queue. */
	struct gxp_queue_info {
	/* A header describing the queue and its state. */
	struct queue_header {
	/* A device-side pointer of the storage managed by this queue */
	uint32_t storage;
	/* The index to the head of the queue. */
	uint32_t head_idx;
	/* The index to the tail of the queue. */
	uint32_t tail_idx;
	/* The size of an element stored this queue. */
	uint32_t element_size;
	/* The number of elements that can be stored in this queue. */
	uint32_t elements_count;
	} header;
	/* The semaphore ID controlling exclusive access to this core. */
	uint32_t access_sem_id;
	/*
	* The ID for the semaphore containing the number of unprocessed items
	* pushed to this queue.
	*/
	uint32_t posted_slots_sem_id;
	/*
	* The ID for the semaphore containing the number of free slots
	* available to store data in this queue.
	*/
	uint32_t free_slots_sem_id;
	};

	/* A struct describing a single core's set of incoming queues. */
	struct gxp_core_info {
	/*
	* The metadata for the queue holding incoming commands from other
	* cores.
	*/
	struct gxp_queue_info incoming_commands_queue;
	/*
	* The metadata for the queue holding incoming responses from other
	* cores.
	*/
	struct gxp_queue_info incoming_responses_queue;
	};

	/* A structure describing all the cores' per-core metadata. */
	struct gxp_cores_descriptor {
	/* The number of cores described in this descriptor. */
	uint32_t num_items;
	/* The descriptors for each core. */
	struct gxp_core_info cores[];
	};

	/*
	* The top level descriptor describing memory regions used to access system-wide
	* structures and resources.
	*/
	struct gxp_system_descriptor {
	/* A device address for the application data descriptor. */
	uint32_t app_descriptor_dev_addr[MAX_NUM_CORES];
	/* A device address for the watchdog descriptor. */
	uint32_t watchdog_dev_addr;
	/* A device address for the telemetry descriptor */
	uint32_t telemetry_dev_addr;
	/* A device address for the common debug dump region */
	uint32_t debug_dump_dev_addr;
	};

	/* A structure describing the metadata belonging to a specific application. */
	struct gxp_application_descriptor {
	/* The ID for this GXP application. */
	uint32_t application_id;
	/* The number of cores this application has. */
	uint16_t core_count;
	/*
	* The cores mask; a bit at index `n` indicates that core `n` is part of
	* this app.
	*/
	uint16_t cores_mask;
	/* The number of threads allocated for each core. */
	uint16_t threads_count;
	/* The size of system memory given to this app. */
	uint32_t system_memory_size;
	/* The device-address of the system memory given to this app. */
	uint32_t system_memory_addr;
	/* The size of TCM memory allocated per bank for this app. */
	uint32_t tcm_memory_per_bank; /* in units of 4 kB */
	/* A device address for the doorbells descriptor. */
	uint32_t doorbells_dev_addr;
	/* A device address for the sync barriers descriptor. */
	uint32_t sync_barriers_dev_addr;
	/* A device address for the semaphores descriptor. */
	uint32_t semaphores_dev_addr;
	/* A device address for the cores cmd/rsp queues descriptor. */
	uint32_t cores_info_dev_addr;
	};

	/* The structure describing a core-to-core command. */
	struct gxp_core_to_core_command {
	/* The source of port number (the core's virtual ID) of the command. */
	uint32_t source;
	/* The command's sequence number. */
	uint64_t sequence_number;
	/* The command payload device address. */
	uint64_t device_address;
	/* The size of the payload in bytes. */
	uint32_t size;
	/* The generic command flags. */
	uint32_t flags;
	};

	/* The structure describing a core-to-core response. */
	struct gxp_core_to_core_response {
	/* The source of port number (the core's virtual ID) of the response. */
	uint32_t source;
	/* The response's sequence number. */
	uint64_t sequence_number;
	/* The response error code (if any). */
	uint16_t error_code;
	/* The response return value (filled-in by the user). */
	int32_t cmd_retval;
	};

	#endif /* __GXP_HOST_DEVICE_STRUCTURES_H__ */