PCAL9555 Driver 0.1.0
API reference
Loading...
Searching...
No Matches
pcal9555_i2c_interface.hpp
Go to the documentation of this file.
1// clang-format off: the hook table below must keep one row per line.
26// clang-format on
27#ifndef PCAL9555_I2C_INTERFACE_HPP
28#define PCAL9555_I2C_INTERFACE_HPP
29
30#include <array>
31#include <concepts>
32#include <cstddef>
33#include <cstdint>
34#include <span>
35
36#include "pcal9555_detail.hpp"
37#include "pcal9555_types.hpp"
38
39namespace pcal9555 {
40
49inline constexpr uint8_t kI2cAddress = kMinI2cAddress;
51inline constexpr uint32_t kMaxClockHz = 400'000U;
54inline constexpr bool kRepeatedStart = true;
65enum class I2cFailure : uint8_t {
66 Other = 0,
67 AddressNack = 1,
68 DataNack = 2,
69};
70
81template <typename Derived>
83public:
85 I2cInterface(const I2cInterface&) = delete;
88
89protected:
91 I2cInterface() noexcept = default;
93 ~I2cInterface() noexcept = default;
94};
95
106template <typename Port>
107concept I2cPort = std::derived_from<Port, I2cInterface<Port>> && requires {
108 detail::ExactHook<Port, bool() noexcept>::Take(&Port::EnsureInitialized);
109 detail::ExactHook<Port, bool(uint8_t, const uint8_t*, std::size_t) noexcept>::Take(&Port::Write);
110 detail::ExactHook<Port, bool(uint8_t, const uint8_t*, std::size_t, uint8_t*,
111 std::size_t) noexcept>::Take(&Port::WriteRead);
112};
113
114namespace detail {
115
116// Optional hooks, all in this one place (KB-CPP-036): a `Declares*` concept only tests the name,
117// the `Has*` concept the exact signature, `noexcept` and the result type. The driver rejects a hook
118// that is declared but does not match (KB-CPP20-007).
119
122template <typename Port>
123concept DeclaresGetLastFailure = requires {
124 &Port::GetLastFailure;
125} || requires(Port& port, I2cFailure& failure) { port.GetLastFailure(failure); };
126
130template <typename Port>
131concept HasGetLastFailure =
132 requires { ExactHook<Port, bool(I2cFailure&) noexcept>::Take(&Port::GetLastFailure); };
133
135template <typename Port>
136concept DeclaresLog =
137 requires { &Port::Log; } || requires(Port& port) { port.Log(LogLevel::Info, ""); };
138
140template <typename Port>
141concept HasLog =
142 requires { ExactHook<Port, void(LogLevel, const char*) noexcept>::Take(&Port::Log); };
143
145template <typename Port>
146void Log(Port& port, [[maybe_unused]] LogLevel level,
147 [[maybe_unused]] const char* message) noexcept {
148 if constexpr (HasLog<Port>) {
149 port.Log(level, message);
150 } else {
151 (void)port;
152 }
153}
154
157template <typename Port>
158[[nodiscard]] Error TransferError(Port& port) noexcept {
159 if constexpr (HasGetLastFailure<Port>) {
160 I2cFailure failure = I2cFailure::Other;
161 if (port.GetLastFailure(failure) && (failure == I2cFailure::AddressNack)) {
162 return Error::NoDevice;
163 }
164 } else {
165 (void)port;
166 }
167 return Error::Bus;
168}
169
171inline constexpr std::size_t kMaxBurst = 2;
172
174template <std::size_t N>
175concept BurstSize = (N >= 1U) && (N <= kMaxBurst);
176
181template <I2cPort Port>
182class RegisterBus {
183public:
184 RegisterBus(Port& port, uint8_t address) noexcept : port_(port), address_(address) {}
185
186 Port& GetPort() & noexcept {
187 return port_;
188 }
189
190 [[nodiscard]] uint8_t GetAddress() const noexcept {
191 return address_;
192 }
193
195 template <std::size_t N>
196 requires BurstSize<N>
197 Error Read(uint8_t reg, std::span<uint8_t, N> out) noexcept {
198 return Read(reg, std::span<uint8_t>{out});
199 }
200
203 Error Read(uint8_t reg, std::span<uint8_t> out) noexcept {
204 if (out.empty() || (out.size() > kMaxBurst)) {
205 return Error::InvalidArgument;
206 }
207 const std::array<uint8_t, 1> command{reg};
208 return port_.WriteRead(address_, command.data(), command.size(), out.data(), out.size())
209 ? Error::Ok
210 : TransferError(port_);
211 }
212
214 template <std::size_t N>
215 requires BurstSize<N>
216 Error Write(uint8_t reg, std::span<const uint8_t, N> data) noexcept {
217 return Write(reg, std::span<const uint8_t>{data});
218 }
219
222 Error Write(uint8_t reg, std::span<const uint8_t> data) noexcept {
223 if (data.empty() || (data.size() > kMaxBurst)) {
224 return Error::InvalidArgument;
225 }
226 std::array<uint8_t, 1U + kMaxBurst> frame{};
227 frame[0] = reg;
228 const std::size_t count = data.size();
229 for (std::size_t i = 0U; i < count; ++i) {
230 frame[1U + i] = data[i];
231 }
232 return port_.Write(address_, frame.data(), count + 1U) ? Error::Ok : TransferError(port_);
233 }
234
235private:
236 Port& port_;
237 uint8_t address_;
238};
239
240} // namespace detail
241
242} // namespace pcal9555
243
244#endif // PCAL9555_I2C_INTERFACE_HPP
CRTP base of the platform I2C port.
Definition pcal9555_i2c_interface.hpp:82
I2cInterface & operator=(const I2cInterface &)=delete
Ports are not copied: the driver holds a reference.
I2cInterface() noexcept=default
Only the derived port is constructed.
I2cInterface(const I2cInterface &)=delete
Ports are not copied: the driver holds a reference.
Satisfied by a class that derives from I2cInterface<Port> and implements the required hooks with exac...
Definition pcal9555_i2c_interface.hpp:107
Error
Why a call failed. Every call of the driver returns one of these in its Result.
Definition pcal9555_types.hpp:36
constexpr uint8_t kMinI2cAddress
Lowest 7-bit I2C address (A2, A1, A0 all low): 0100 A2 A1 A0 (data sheet section 6....
Definition pcal9555_types.hpp:249
The PCAL9555 driver: everything it declares lives here; internals in detail.
Definition pcal9555.hpp:26
constexpr uint32_t kMaxClockHz
Highest SCL frequency: fast mode, 400 kHz (section 13, table 33, f_SCL).
Definition pcal9555_i2c_interface.hpp:51
I2cFailure
Why a Write() or WriteRead() hook returned false, as the optional GetLastFailure() hook reports it.
Definition pcal9555_i2c_interface.hpp:65
@ DataNack
The device acknowledged its address, then did not acknowledge a data byte.
@ AddressNack
No device acknowledged the address byte.
@ Other
Arbitration lost, a stuck line, a timeout, or a NACK the port cannot place.
constexpr bool kRepeatedStart
Definition pcal9555_i2c_interface.hpp:54
constexpr uint8_t kI2cAddress
Definition pcal9555_i2c_interface.hpp:49
Compile-time helpers of the PCAL9555 driver: exact hook matching and enumeration checks.
Public types of the PCAL9555 driver: errors, Result<T>, pins and configuration.