device.h

// Copyright 2021 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 <utility>
 
#include "pw_bytes/span.h"
#include "pw_spi/chip_selector.h"
#include "pw_spi/initiator.h"
#include "pw_status/status.h"
#include "pw_status/try.h"
#include "pw_sync/borrow.h"
 
namespace pw::spi {
 
 
class Device {
 public:
  Device(sync::Borrowable<Initiator> initiator,
         const Config config,
         ChipSelector& selector)
      : initiator_(initiator), config_(config), selector_(selector) {}
 
  ~Device() = default;
 
  Status Read(ByteSpan read_buffer) { return WriteRead({}, read_buffer); }
 
  Status Write(ConstByteSpan write_buffer) {
    return WriteRead(write_buffer, {});
  }
 
  Status WriteRead(ConstByteSpan write_buffer, ByteSpan read_buffer) {
    return StartTransaction(ChipSelectBehavior::kPerWriteRead)
        .WriteRead(write_buffer, read_buffer);
  }
 
  class Transaction final {
   public:
    Transaction() = delete;
    ~Transaction() {
      if ((selector_ != nullptr) &&
          (behavior_ == ChipSelectBehavior::kPerTransaction) &&
          (!first_write_read_)) {
        selector_->Deactivate()
            .IgnoreError();  // TODO: b/242598609 - Handle Status properly
      }
    }
 
    Transaction(Transaction&& other)
        : initiator_(std::move(other.initiator_)),
          config_(other.config_),
          selector_(other.selector_),
          behavior_(other.behavior_),
          first_write_read_(other.first_write_read_) {
      other.selector_ = nullptr;
    }
 
    Transaction& operator=(Transaction&& other) {
      initiator_ = std::move(other.initiator_);
      config_ = other.config_;
      selector_ = other.selector_;
      other.selector_ = nullptr;
      behavior_ = other.behavior_;
      first_write_read_ = other.first_write_read_;
      return *this;
    }
 
    Transaction(const Transaction&) = delete;
    Transaction& operator=(const Transaction&) = delete;
 
    Status Read(ByteSpan read_buffer) { return WriteRead({}, read_buffer); }
 
    Status Write(ConstByteSpan write_buffer) {
      return WriteRead(write_buffer, {});
    }
 
    Status WriteRead(ConstByteSpan write_buffer, ByteSpan read_buffer) {
      // Lazy-init: Configure the SPI bus when performing the first transfer in
      // a transaction.
      if (first_write_read_) {
        PW_TRY(initiator_->Configure(config_));
      }
 
      if ((behavior_ == ChipSelectBehavior::kPerWriteRead) ||
          (first_write_read_)) {
        PW_TRY(selector_->Activate());
        first_write_read_ = false;
      }
 
      auto status = initiator_->WriteRead(write_buffer, read_buffer);
 
      if (behavior_ == ChipSelectBehavior::kPerWriteRead) {
        PW_TRY(selector_->Deactivate());
      }
 
      return status;
    }
 
   private:
    friend Device;
    explicit Transaction(sync::BorrowedPointer<Initiator> initiator,
                         const Config& config,
                         ChipSelector& selector,
                         ChipSelectBehavior& behavior)
        : initiator_(std::move(initiator)),
          config_(config),
          selector_(&selector),
          behavior_(behavior),
          first_write_read_(true) {}
 
    sync::BorrowedPointer<Initiator> initiator_;
    Config config_;
    ChipSelector* selector_;
    ChipSelectBehavior behavior_;
    bool first_write_read_;
  };
 
  Transaction StartTransaction(ChipSelectBehavior behavior) {
    return Transaction(initiator_.acquire(), config_, selector_, behavior);
  }
 
 private:
  sync::Borrowable<Initiator> initiator_;
  const Config config_;
  ChipSelector& selector_;
};
 
 
}  // namespace pw::spi