1 // Copyright 2021 The Pigweed Authors 2 // 3 // Licensed under the Apache License, Version 2.0 (the "License"); you may not 4 // use this file except in compliance with the License. You may obtain a copy of 5 // the License at 6 // 7 // https://www.apache.org/licenses/LICENSE-2.0 8 // 9 // Unless required by applicable law or agreed to in writing, software 10 // distributed under the License is distributed on an "AS IS" BASIS, WITHOUT 11 // WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the 12 // License for the specific language governing permissions and limitations under 13 // the License. 14 15 #pragma once 16 17 #include <cstdint> 18 19 #include "pw_status/status.h" 20 21 namespace pw::spi { 22 23 /// Configuration data used to determine how the Chip Select signal is 24 /// controlled throughout a transaction. 25 /// 26 /// `kPerWriteRead` indicates that the chip-select signal should be 27 /// activated/deactivated between calls to WriteRead() 28 enum class ChipSelectBehavior : uint8_t { 29 kPerWriteRead, 30 kPerTransaction, 31 }; 32 33 /// The ChipSelector class provides an abstract interface for controlling the 34 /// chip-select signal associated with a specific SPI responder. 35 /// 36 /// This interface provides a `SetActive()` method, which activates/deactivates 37 /// the device based on the value of the `active` parameter. The associated 38 /// `Activate()` and `Deactivate()` methods are utility wrappers for 39 /// `SetActive(true)` and `SetActive(false)`, respectively. 40 /// 41 /// A concrete implementation of this interface class must be provided in order 42 /// to use the SPI HAL to communicate with a responder. 43 /// 44 /// @note `Active` does not imply a specific logic-level; it is left to the 45 /// implementor to correctly map logic-levels to the device's active/inactive 46 /// states. 47 class ChipSelector { 48 public: 49 virtual ~ChipSelector() = default; 50 51 /// SetActive sets the state of the chip-select signal to the value 52 /// represented by the `active` parameter. Passing a value of `true` will 53 /// activate the chip-select signal, and `false` will deactivate the 54 /// chip-select signal. 55 /// 56 /// @returns @rst 57 /// 58 /// .. pw-status-codes:: 59 /// 60 /// OK: Success. 61 /// 62 /// Returns other implementation-specific values on failure. 63 /// 64 /// @endrst 65 virtual Status SetActive(bool active) = 0; 66 67 /// Helper method to activate the chip-select signal. 68 /// 69 /// @returns @rst 70 /// 71 /// .. pw-status-codes:: 72 /// 73 /// OK: Success. 74 /// 75 /// Returns other implementation-specific values on failure. 76 /// 77 /// @endrst Activate()78 Status Activate() { return SetActive(true); } 79 80 /// Helper method to deactivate the chip-select signal. 81 /// 82 /// @returns @rst 83 /// 84 /// .. pw-status-codes:: 85 /// 86 /// OK: Success. 87 /// 88 /// Returns other implementation-specific values on failure. 89 /// 90 /// @endrst Deactivate()91 Status Deactivate() { return SetActive(false); } 92 }; 93 94 } // namespace pw::spi 95