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