1 // Copyright 2024 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::uart { 22 23 /// The common abstract base class of the UART interface. 24 /// 25 /// The `UartBase` interface provides basic method for enabling and configuring 26 /// a UART. Methods for actually communicating via the UART are on the `Uart` 27 /// and `UartNonBlocking` child classes. 28 29 class UartBase { 30 public: 31 virtual ~UartBase() = default; 32 33 /// Initializes the UART module, sets it into the default state as determined 34 /// by the concrete UART implementation. This function should be a no-op if 35 /// the UART module is in an enabled state. 36 /// 37 /// This may change the power state of the UART module, configure the 38 /// interface parameters, enable the associated pins, setup the internal 39 /// TX and RX buffers, etc... 40 /// 41 /// @returns @rst 42 /// 43 /// .. pw-status-codes:: 44 /// 45 /// OK: The UART module has been successfully initialized. 46 /// 47 /// INTERNAL: Internal errors within the hardware abstraction layer. 48 /// 49 /// @endrst Enable()50 Status Enable() { return DoEnable(true); } 51 52 /// Disables the UART module. Disabling the UART shuts down communication and 53 /// prevents the microcontroller from sending or receiving data through the 54 /// UART port. 55 /// 56 /// This is usually done to save power. Interrupt handlers should also be 57 /// disabled. 58 /// 59 /// @returns @rst 60 /// 61 /// .. pw-status-codes:: 62 /// 63 /// OK: The UART module has been successfully initialized. 64 /// 65 /// INTERNAL: Internal errors within the hardware abstraction layer. 66 /// 67 /// @endrst Disable()68 Status Disable() { return DoEnable(false); } 69 70 /// Configures the UART communication baud rate. 71 /// 72 /// This function sets the communication speed (baud rate) for the UART. 73 /// Whether the baud rate can be changed while the UART is enabled depends on 74 /// the specific implementation. 75 /// 76 /// @returns @rst 77 /// 78 /// .. pw-status-codes:: 79 /// 80 /// OK: The UART has been successfully initialized. 81 /// 82 /// FAILED_PRECONDITION: The device is enabled and does not support 83 /// changing settings on the fly. 84 /// 85 /// INTERNAL: Internal errors within the hardware abstraction layer. 86 /// 87 /// @endrst SetBaudRate(uint32_t baud_rate)88 Status SetBaudRate(uint32_t baud_rate) { return DoSetBaudRate(baud_rate); } 89 90 /// Configures the UART hardware flow control enable. 91 /// 92 /// This function sets the hardware flow control enable for the UART. 93 /// Whether the flow control setting rate can be changed while the UART is 94 /// enabled depends on the specific implementation. 95 /// 96 /// @returns @rst 97 /// 98 /// .. pw-status-codes:: 99 /// 100 /// OK: The UART has been successfully initialized. 101 /// 102 /// FAILED_PRECONDITION: The device is enabled and does not support 103 /// changing settings on the fly. 104 /// 105 /// UNIMPLEMENTED: The device does not support flow control. 106 /// 107 /// INTERNAL: Internal errors within the hardware abstraction layer. 108 /// 109 /// @endrst SetFlowControl(bool enable)110 Status SetFlowControl(bool enable) { return DoSetFlowControl(enable); } 111 112 /// Returns the number of bytes currently available for reading. 113 /// 114 /// This function checks the receive buffer to determine how many bytes of 115 /// data are ready to be read. 116 /// 117 /// @returns The number of bytes available for reading. When no data is 118 /// available or in case of an error this function returns 0. ConservativeReadAvailable()119 size_t ConservativeReadAvailable() { return DoConservativeReadAvailable(); } 120 121 /// Empties the UART's receive buffer and discards any unread data. 122 /// 123 /// This function removes all data from the receive buffer, resetting the 124 /// buffer to an empty state. This is useful for situations where you want to 125 /// disregard any previously received data and resynchronize. 126 /// 127 /// @returns @rst 128 /// 129 /// .. pw-status-codes:: 130 /// 131 /// OK: The operation was successful. 132 /// 133 /// May return other implementation-specific status codes. 134 /// 135 /// @endrst ClearPendingReceiveBytes()136 Status ClearPendingReceiveBytes() { return DoClearPendingReceiveBytes(); } 137 138 private: 139 virtual Status DoEnable(bool enable) = 0; 140 virtual Status DoSetBaudRate(uint32_t baud_rate) = 0; DoSetFlowControl(bool)141 virtual Status DoSetFlowControl(bool /*enable*/) { 142 return pw::Status::Unimplemented(); 143 } 144 virtual size_t DoConservativeReadAvailable() = 0; 145 virtual Status DoClearPendingReceiveBytes() = 0; 146 }; 147 148 } // namespace pw::uart 149