Skip to content
Snippets Groups Projects
Unverified Commit 5ec40711 authored by Peter Harper's avatar Peter Harper Committed by GitHub
Browse files

Some doc issues (#1772)

* Fix doxygen for uart example

Fixes https://github.com/raspberrypi/pico-sdk/issues/1685

* Clarify uart write

will block until data "has been sent to the UART transmit buffer"

Fixes https://github.com/raspberrypi/pico-sdk/issues/1481

* Add note to flash API about erasing sectors

Fixes: https://github.com/raspberrypi/pico-sdk/issues/650
parent 6328fffc
No related branches found
No related tags found
No related merge requests found
...@@ -56,6 +56,10 @@ extern "C" { ...@@ -56,6 +56,10 @@ extern "C" {
* *
* \param flash_offs Offset into flash, in bytes, to start the erase. Must be aligned to a 4096-byte flash sector. * \param flash_offs Offset into flash, in bytes, to start the erase. Must be aligned to a 4096-byte flash sector.
* \param count Number of bytes to be erased. Must be a multiple of 4096 bytes (one sector). * \param count Number of bytes to be erased. Must be a multiple of 4096 bytes (one sector).
*
* @note Erasing a flash sector sets all the bits in all the pages in that sector to one.
* You can then "program" flash pages in the sector to turn some of the bits to zero.
* Once a bit is set to zero it can only be changed back to one by erasing the whole sector again.
*/ */
void flash_range_erase(uint32_t flash_offs, size_t count); void flash_range_erase(uint32_t flash_offs, size_t count);
...@@ -65,6 +69,10 @@ void flash_range_erase(uint32_t flash_offs, size_t count); ...@@ -65,6 +69,10 @@ void flash_range_erase(uint32_t flash_offs, size_t count);
* \param flash_offs Flash address of the first byte to be programmed. Must be aligned to a 256-byte flash page. * \param flash_offs Flash address of the first byte to be programmed. Must be aligned to a 256-byte flash page.
* \param data Pointer to the data to program into flash * \param data Pointer to the data to program into flash
* \param count Number of bytes to program. Must be a multiple of 256 bytes (one page). * \param count Number of bytes to program. Must be a multiple of 256 bytes (one page).
*
* @note: Programming a flash page effectively changes some of the bits from one to zero.
* The only way to change a zero bit back to one is to "erase" the whole sector that the page resides in.
* So you may need to make sure you have called flash_range_erase before calling flash_range_program.
*/ */
void flash_range_program(uint32_t flash_offs, const uint8_t *data, size_t count); void flash_range_program(uint32_t flash_offs, const uint8_t *data, size_t count);
......
...@@ -56,13 +56,14 @@ extern "C" { ...@@ -56,13 +56,14 @@ extern "C" {
* \code * \code
* int main() { * int main() {
* *
* // Initialise UART 0
* uart_init(uart0, 115200);
*
* // Set the GPIO pin mux to the UART - 0 is TX, 1 is RX * // Set the GPIO pin mux to the UART - 0 is TX, 1 is RX
* // Do this before calling uart_init to avoid losing data
* gpio_set_function(0, GPIO_FUNC_UART); * gpio_set_function(0, GPIO_FUNC_UART);
* gpio_set_function(1, GPIO_FUNC_UART); * gpio_set_function(1, GPIO_FUNC_UART);
* *
* // Initialise UART 0
* uart_init(uart0, 115200);
*
* uart_puts(uart0, "Hello world!"); * uart_puts(uart0, "Hello world!");
* } * }
* \endcode * \endcode
...@@ -310,7 +311,7 @@ static inline bool uart_is_readable(uart_inst_t *uart) { ...@@ -310,7 +311,7 @@ static inline bool uart_is_readable(uart_inst_t *uart) {
/*! \brief Write to the UART for transmission. /*! \brief Write to the UART for transmission.
* \ingroup hardware_uart * \ingroup hardware_uart
* *
* This function will block until all the data has been sent to the UART * This function will block until all the data has been sent to the UART transmit buffer
* *
* \param uart UART instance. \ref uart0 or \ref uart1 * \param uart UART instance. \ref uart0 or \ref uart1
* \param src The bytes to send * \param src The bytes to send
...@@ -347,7 +348,7 @@ static inline void uart_read_blocking(uart_inst_t *uart, uint8_t *dst, size_t le ...@@ -347,7 +348,7 @@ static inline void uart_read_blocking(uart_inst_t *uart, uint8_t *dst, size_t le
/*! \brief Write single character to UART for transmission. /*! \brief Write single character to UART for transmission.
* \ingroup hardware_uart * \ingroup hardware_uart
* *
* This function will block until the entire character has been sent * This function will block until the entire character has been sent to the UART transmit buffer
* *
* \param uart UART instance. \ref uart0 or \ref uart1 * \param uart UART instance. \ref uart0 or \ref uart1
* \param c The character to send * \param c The character to send
...@@ -359,7 +360,7 @@ static inline void uart_putc_raw(uart_inst_t *uart, char c) { ...@@ -359,7 +360,7 @@ static inline void uart_putc_raw(uart_inst_t *uart, char c) {
/*! \brief Write single character to UART for transmission, with optional CR/LF conversions /*! \brief Write single character to UART for transmission, with optional CR/LF conversions
* \ingroup hardware_uart * \ingroup hardware_uart
* *
* This function will block until the character has been sent * This function will block until the character has been sent to the UART transmit buffer
* *
* \param uart UART instance. \ref uart0 or \ref uart1 * \param uart UART instance. \ref uart0 or \ref uart1
* \param c The character to send * \param c The character to send
...@@ -376,7 +377,7 @@ static inline void uart_putc(uart_inst_t *uart, char c) { ...@@ -376,7 +377,7 @@ static inline void uart_putc(uart_inst_t *uart, char c) {
/*! \brief Write string to UART for transmission, doing any CR/LF conversions /*! \brief Write string to UART for transmission, doing any CR/LF conversions
* \ingroup hardware_uart * \ingroup hardware_uart
* *
* This function will block until the entire string has been sent * This function will block until the entire string has been sent to the UART transmit buffer
* *
* \param uart UART instance. \ref uart0 or \ref uart1 * \param uart UART instance. \ref uart0 or \ref uart1
* \param s The null terminated string to send * \param s The null terminated string to send
......
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment