initiator.h

// Copyright 2020 The Pigweed Authors
//
// Licensed under the Apache License, Version 2.0 (the "License"); you may not
// use this file except in compliance with the License. You may obtain a copy of
// the License at
//
//     https://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
// License for the specific language governing permissions and limitations under
// the License.
#pragma once
 
#include <cstdint>
#include <utility>
 
#include "pw_bytes/span.h"
#include "pw_chrono/system_clock.h"
#include "pw_i2c/address.h"
#include "pw_i2c/message.h"
#include "pw_status/status.h"
 
namespace pw::i2c {
 
class Initiator {
 public:
  enum class Feature : int {
    // Initiator does not support extended features.
    kStandard = 0,
 
    // Initiator supports 10-bit addressing mode
    kTenBit = (1 << 0),
 
    // Initiator supports sending bytes without a start condition or address.
    kNoStart = (1 << 1),
  };
 
  [[deprecated("Use the Initiator(Feature) constructor")]]
  constexpr Initiator()
      : Initiator(kCompatibilityFeatures) {}
 
  explicit constexpr Initiator(Feature supported_features)
      : supported_features_(supported_features) {}
 
  virtual ~Initiator() = default;
 
  Status WriteReadFor(Address device_address,
                      ConstByteSpan tx_buffer,
                      ByteSpan rx_buffer,
                      chrono::SystemClock::duration timeout) {
    return DoWriteReadFor(device_address, tx_buffer, rx_buffer, timeout);
  }
 
  Status TransferFor(span<const Message> messages,
                     chrono::SystemClock::duration timeout) {
    return DoValidateAndTransferFor(messages, timeout);
  }
 
  Status WriteReadFor(Address device_address,
                      const void* tx_buffer,
                      size_t tx_size_bytes,
                      void* rx_buffer,
                      size_t rx_size_bytes,
                      chrono::SystemClock::duration timeout) {
    return WriteReadFor(
        device_address,
        span(static_cast<const std::byte*>(tx_buffer), tx_size_bytes),
        span(static_cast<std::byte*>(rx_buffer), rx_size_bytes),
        timeout);
  }
 
  Status WriteFor(Address device_address,
                  ConstByteSpan tx_buffer,
                  chrono::SystemClock::duration timeout) {
    return WriteReadFor(device_address, tx_buffer, ByteSpan(), timeout);
  }
  Status WriteFor(Address device_address,
                  const void* tx_buffer,
                  size_t tx_size_bytes,
                  chrono::SystemClock::duration timeout) {
    return WriteFor(
        device_address,
        span(static_cast<const std::byte*>(tx_buffer), tx_size_bytes),
        timeout);
  }
 
  Status ReadFor(Address device_address,
                 ByteSpan rx_buffer,
                 chrono::SystemClock::duration timeout) {
    return WriteReadFor(device_address, ConstByteSpan(), rx_buffer, timeout);
  }
  Status ReadFor(Address device_address,
                 void* rx_buffer,
                 size_t rx_size_bytes,
                 chrono::SystemClock::duration timeout) {
    return ReadFor(device_address,
                   span(static_cast<std::byte*>(rx_buffer), rx_size_bytes),
                   timeout);
  }
 
  Status ProbeDeviceFor(Address device_address,
                        chrono::SystemClock::duration timeout) {
    std::byte ignored_buffer[1] = {};  // Read a byte to probe.
    return WriteReadFor(
        device_address, ConstByteSpan(), ignored_buffer, timeout);
  }
 
 private:
  static constexpr Feature kCompatibilityFeatures = Feature::kTenBit;
 
  // This function should not be overridden by future implementations of
  // Initiator unless dealing with an underlying interface that prefers
  // this format.
  // Implement DoTransferFor(Messages) as a preferred course of action.
  //
  // The default implementation of this function will forward calls to
  // TransferFor().
  //
  // Both the read and write parameters should be transmitted in one bus
  // operation using a repeated start condition.
  // If both parameters are present, the write operation is performed first.
  virtual Status DoWriteReadFor(Address,
                                ConstByteSpan,
                                ByteSpan,
                                chrono::SystemClock::duration);
 
  // This method should be overridden by implementations of Initiator.
  // All messages in one call to DoTransferFor() should be executed
  // as one bus transaction with repeated starts.
  //
  // The default implementation returns Status::Unimplemented().
  virtual Status DoTransferFor(span<const Message> messages,
                               chrono::SystemClock::duration timeout);
 
  // Function to wrap calls to DoTransferFor() and Validate message vector's
  // contents.
  [[nodiscard]] Status DoValidateAndTransferFor(
      span<const Message> messages, chrono::SystemClock::duration timeout);
 
  Status ValidateMessages(span<const Message> messages) const;
 
  [[nodiscard]] Status ValidateMessageFeatures(const Message& msg) const;
 
  bool IsSupported(Feature feature) const;
 
  // Features supported by this Initiator.
  Feature supported_features_ = Feature::kStandard;
};
 
inline constexpr Initiator::Feature operator|(Initiator::Feature a,
                                              Initiator::Feature b) {
  return static_cast<Initiator::Feature>(static_cast<int>(a) |
                                         static_cast<int>(b));
}
 
}  // namespace pw::i2c