1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
|
// 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 {
// The Device class enables data transfer with a specific SPI peripheral.
// This class combines an Initiator (representing the physical SPI bus), its
// configuration data, and the ChipSelector object to uniquely address a device.
// Transfers to a selected initiator are guarded against concurrent access
// through the use of the `Borrowable` object.
class Device {
public:
Device(sync::Borrowable<Initiator>& initiator,
const Config config,
ChipSelector& selector)
: initiator_(initiator), config_(config), selector_(selector) {}
~Device() = default;
// Synchronously read data from the SPI peripheral until the provided
// `read_buffer` is full.
// This call will configure the bus and activate/deactivate chip select
// for the transfer
//
// Note: This call will block in the event that other clients are currently
// performing transactions using the same SPI Initiator.
// Returns OkStatus() on success, and implementation-specific values on
// failure.
Status Read(ByteSpan read_buffer) { return WriteRead({}, read_buffer); }
// Synchronously write the contents of `write_buffer` to the SPI peripheral.
// This call will configure the bus and activate/deactivate chip select
// for the transfer
//
// Note: This call will block in the event that other clients are currently
// performing transactions using the same SPI Initiator.
// Returns OkStatus() on success, and implementation-specific values on
// failure.
Status Write(ConstByteSpan write_buffer) {
return WriteRead(write_buffer, {});
}
// Perform a synchronous read/write transfer with the SPI peripheral. Data
// from the `write_buffer` object is written to the bus, while the
// `read_buffer` is populated with incoming data on the bus. In the event
// the read buffer is smaller than the write buffer (or zero-size), any
// additional input bytes are discarded. In the event the write buffer is
// smaller than the read buffer (or zero size), the output is padded with
// 0-bits for the remainder of the transfer.
// This call will configure the bus and activate/deactivate chip select
// for the transfer
//
// Note: This call will block in the event that other clients
// are currently performing transactions using the same SPI Initiator.
// Returns OkStatus() on success, and implementation-specific values on
// failure.
Status WriteRead(ConstByteSpan write_buffer, ByteSpan read_buffer) {
return StartTransaction(ChipSelectBehavior::kPerWriteRead)
.WriteRead(write_buffer, read_buffer);
}
// RAII Object providing exclusive access to the SPI device. Enables
// thread-safe Read()/Write()/WriteRead() operations, as well as composite
// operations consisting of multiple, uninterrupted transfers, with
// configurable chip-select behavior.
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 objects are moveable but not copyable
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;
// Synchronously read data from the SPI peripheral until the provided
// `read_buffer` is full.
//
// Returns OkStatus() on success, and implementation-specific values on
// failure.
Status Read(ByteSpan read_buffer) { return WriteRead({}, read_buffer); }
// Synchronously write the contents of `write_buffer` to the SPI peripheral
//
// Returns OkStatus() on success, and implementation-specific values on
// failure.
Status Write(ConstByteSpan write_buffer) {
return WriteRead(write_buffer, {});
}
// Perform a synchronous read/write transfer on the SPI bus. Data from the
// `write_buffer` object is written to the bus, while the `read_buffer` is
// populated with incoming data on the bus. The operation will ensure that
// all requested data is written-to and read-from the bus. In the event the
// read buffer is smaller than the write buffer (or zero-size), any
// additional input bytes are discarded. In the event the write buffer is
// smaller than the read buffer (or zero size), the output is padded with
// 0-bits for the remainder of the transfer.
//
// Returns OkStatus() on success, and implementation-specific values on
// failure.
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_;
};
// Begin a transaction with the SPI device. This creates an RAII
// `Transaction` object that ensures that only one entity can access the
// underlying SPI bus (Initiator) for the object's duration. The `behavior`
// parameter provides a means for a client to select how the chip-select
// signal will be applied on Read/Write/WriteRead calls taking place with the
// Transaction object. A value of `kPerWriteRead` will activate/deactivate
// chip-select on each operation, while `kPerTransaction` will hold the
// chip-select active for the duration of the Transaction object.
Transaction StartTransaction(ChipSelectBehavior behavior) {
return Transaction(initiator_.acquire(), config_, selector_, behavior);
}
private:
sync::Borrowable<Initiator>& initiator_;
const Config config_;
ChipSelector& selector_;
};
} // namespace pw::spi
|
