//  @file sns_async_com_port.proto
//
//  Defines standard message types for the Async Com Port
//
// Copyright (c) 2016-2018, 2020 Qualcomm Technologies, Inc.
// All Rights Reserved.
// Confidential and Proprietary - Qualcomm Technologies, Inc.

syntax = "proto2";
import "nanopb.proto";
import "sns_std.proto";

// Asynchronous Com Port
//
// The Asynchronous Com Port provides access to buses like I2C, I3C, SPI and others.
// A complete list of all buses available in the sns_async_com_port_bus_type enum.
//
// The Asynchronous Com Port can perform read and write operations on these buses
// asynchronously. This is the recommended way to perform large bus reads (example:
// reading a large FIFO buffer). This file describes the use of the async com port
// (ascp) API.
//
// First, the client must configure the port using the sns_async_com_port_config
// message.
//
// To perform one or more read or write operations, the client should send the
// sns_async_com_port_vector_rw message.
//
// A single sns_async_com_port_vector_rw message can contain multiple
// sns_async_com_port_vector messages, the async com port will efficiently perform
// all the transactions that are part of the parent sns_async_com_port_vector_rw
// message. The results of the transaction will be sent as an sns_async_com_port_vector_rw
// event.
//
// The async com port will internally manage efficiently opening and closing the
// bus power lines and clock settings. The async com port can safely be used along
// with the synchronous com port service.
//
// To help with encoding and decoding the sns_async_com_port_vector_rw messages,
// utility functions are provided in sns_async_com_port_pb_utils.h


// The operation to be performed by the async com port
enum sns_async_com_port_operation_type
{
  option (nanopb_enumopt).long_names = false;

  SNS_ASYNC_COM_PORT_OPERATION_TYPE_READ = 0;
  SNS_ASYNC_COM_PORT_OPERATION_TYPE_WRITE = 1;
}

// The bus type to be accessed by the async com port
enum sns_async_com_port_bus_type
{
  option (nanopb_enumopt).long_names = false;

  // I2C bus:
  SNS_ASYNC_COM_PORT_BUS_TYPE_I2C            = 0;

  // SPI bus:
  SNS_ASYNC_COM_PORT_BUS_TYPE_SPI            = 1;

  // I3C bus, standard data rate:
  SNS_ASYNC_COM_PORT_BUS_TYPE_I3C_SDR        = 3;

  // I3C bus, double data rate:
  SNS_ASYNC_COM_PORT_BUS_TYPE_I3C_HDR_DDR    = 4;

  // I3C bus, legacy I2C device attached to I3C bus:
  SNS_ASYNC_COM_PORT_BUS_TYPE_I3C_I2C_LEGACY = 5;
}

// The registry address type to be used by async com port
enum sns_async_com_port_reg_addr_type
{
  option (nanopb_enumopt).long_names = false;

  SNS_ASYNC_COM_PORT_REG_ADDR_TYPE_8_BIT = 0;
  SNS_ASYNC_COM_PORT_REG_ADDR_TYPE_16_BIT = 1;
  SNS_ASYNC_COM_PORT_REG_ADDR_TYPE_32_BIT = 2;
}

// Configuration message
message sns_async_com_port_config
{
  // The bus type
  required sns_async_com_port_bus_type bus_type = 1;

  // Slave Address for I2C.
  // Dynamic slave address for I3C.
  // Chip Select for SPI.
  required fixed32 slave_control = 2;

  // Register address type for the slave
  required sns_async_com_port_reg_addr_type reg_addr_type = 3;

  // Minimum bus clock supported by slave in kHz
  required fixed32 min_bus_speed_kHz = 4;

  // Maximum bus clock supported by slave in kHz
  required fixed32 max_bus_speed_kHz = 5;

  // Platform bus instance number (BLSP number)
  required fixed32 bus_instance = 6;
}

// A single read or write operation.
message sns_async_com_port_vector
{
  // Read or write operation
  required sns_async_com_port_operation_type operation = 1;

  // Register address
  required fixed32 reg_addr = 2;


  // Number of bytes to read or write.
  // The async com port will ignore this field for a write
  // operation and use the size of the buffer present in the message.
  //
  // For events generated by the async com port, this field will always match the
  // size of the buffer when it is present.
  optional fixed32 num_bytes = 3;

  // Buffer
  // The async com port will ignore this field in a request for a read operation.
  optional bytes buffer = 4;
}


// A collection of read and write operations
message sns_async_com_port_vector_rw
{
  // Number of operations
  required fixed32 num_vectors = 1;

  // Read/write operations
  repeated sns_async_com_port_vector vectors = 2;
}

// Notifies the client of an error during a transaction
message sns_async_com_port_error
{
  // Registry address
  required fixed32 reg_addr = 1;

  // Number of bytes that was to be read/written
  required fixed32 num_bytes = 2;

  // Error code
  required sns_std_error error_code = 3;
}


// Message IDs
enum sns_async_com_port_msgid
{
  option (nanopb_enumopt).long_names = false;

  SNS_ASYNC_COM_PORT_MSGID_SNS_ASYNC_COM_PORT_CONFIG = 512;
  SNS_ASYNC_COM_PORT_MSGID_SNS_ASYNC_COM_PORT_VECTOR_RW = 1024;
  SNS_ASYNC_COM_PORT_MSGID_SNS_ASYNC_COM_PORT_ERROR = 1025;
  SNS_ASYNC_COM_PORT_MSGID_SNS_ASYNC_COM_PORT_REG = 1026;
}


