/* 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 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) /* 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 (loggging 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[NUM_CORES], per_core_tracers[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[NUM_CORES]; /* * A mapping of which doorbells to use as a wakeup signal source per * core. */ uint32_t wakeup_doorbells[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[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 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__ */