aarch64/raspberrypi: improve UART

- Add support for four new ports, UART2-UART5.
- Add build options to allow console device configuration.
- Segregate device-specific definitions from the device family files. X macros
  are used to maintain a single source of truth and have the configuration
  done at compile-time
- Add raspberrypi_uart_init() to make it convenient for users to install uart
  devices

Close #5130

Co-authored-by: Ning Yang <yangn0@qq.com>

bsps/aarch64/raspberrypi/console/console.c

@@ -3,14 +3,15 @@
 /**
  * @file
  *
- * @ingroup RTEMSBSPsAArch64Raspberrypi4
+ * @ingroup RTEMSBSPsAArch64RaspberryPi
  *
  * @brief Console Configuration
  */
 
 /*
  * Copyright (C) 2022 Mohd Noor Aman
- *
+ * Copyright (C) 2023 Utkarsh Verma
+ * Copyright (C) 2024 Ning Yang
  *
  * Redistribution and use in source and binary forms, with or without
  * modification, are permitted provided that the following conditions
@@ -38,35 +39,143 @@
 
 #include <bsp.h>
 #include <dev/serial/arm-pl011.h>
-#include <bsp/console-termios.h>
 #include <bsp/irq.h>
-
+#include <bsp/console.h>
+#include <bsp/fatal.h>
+#include <bsp/rpi-gpio.h>
 #include <bspopts.h>
 
-arm_pl011_context raspberrypi_4_context = {
-  .base = RTEMS_TERMIOS_DEVICE_CONTEXT_INITIALIZER("PL011"),
-  .regs = (arm_pl011_uart *)BSP_RPI4_PL011_BASE,
-  .initial_baud = 115200,
-  .clock = 48000000,
-  .irq = BCM2711_IRQ_PL011_UART
+#include <rtems/console.h>
+#include <rtems/rtems/status.h>
+#include <rtems/termiosdevice.h>
+#include <stdint.h>
+
+#define CONSOLE_DEVICE_CONTEXT_NAME(port_no) uart##port_no##_context
+
+#define CONSOLE_DEVICE_CONTEXT( \
+  port_no, _file_name, regs_base, _size, clock_freq, irq_no, \
+  context_type, ... \
+) \
+static context_type CONSOLE_DEVICE_CONTEXT_NAME(port_no) = { \
+  .base   = RTEMS_TERMIOS_DEVICE_CONTEXT_INITIALIZER("UART" #port_no), \
+  .regs = (volatile arm_pl011_uart *) regs_base, \
+  .clock     = clock_freq, \
+  .initial_baud = 115200, \
+  .irq          = irq_no, \
 };
 
-const console_device console_device_table[] = {
-  {
-    .device_file = "/dev/ttyS0",
-    .probe = console_device_probe_default,
-    .handler = &arm_pl011_fns,
-    .context = &raspberrypi_4_context.base
-  }
+#define CONSOLE_DEVICE( \
+  port_no, file_name, _base, _size, _clock, _irq,_context_type, dev_handler, \
+  write_char_func, rx_pin, tx_pin, gpio_func, ... \
+) \
+[CONSOLE_DEVICE_PORT2ENUM(port_no)] = { \
+  .file    = file_name, \
+  .context = &CONSOLE_DEVICE_CONTEXT_NAME(port_no).base, \
+  .gpio    = {.rx = rx_pin, .tx = tx_pin, .function = gpio_func}, \
+  .handler = dev_handler, \
+  .write_char_polled = write_char_func, \
+},
+
+typedef struct {
+    const unsigned int rx;
+    const unsigned int tx;
+    const raspberrypi_gpio_function function;
+} raspberrypi_console_device_gpio_config;
+
+typedef struct {
+    const char* file;
+    rtems_termios_device_context* context;
+    const raspberrypi_console_device_gpio_config gpio;
+
+    const rtems_termios_device_handler* handler;
+    void (*write_char_polled)(rtems_termios_device_context*, char);
+} raspberrypi_console_device;
+
+/* Initialize all console device contexts */
+CONSOLE_DEVICES(CONSOLE_DEVICE_CONTEXT)
+
+/* Initialize all device configurations */
+static const raspberrypi_console_device devices[CONSOLE_DEVICE_COUNT] = {
+  CONSOLE_DEVICES(CONSOLE_DEVICE)
 };
 
-const size_t console_device_count = RTEMS_ARRAY_SIZE(console_device_table);
-
-static void output_char( char c )
+static rtems_status_code console_device_init_gpio(
+  const raspberrypi_console_device_gpio_config *gpio
+)
 {
-  arm_pl011_write_polled(&raspberrypi_4_context.base, c);
+  rtems_status_code status = raspberrypi_gpio_set_function(
+    gpio->rx,
+    gpio->function
+  );
+  if (status != RTEMS_SUCCESSFUL)
+    return status;
+  
+  status = raspberrypi_gpio_set_function(gpio->tx, gpio->function);
+  if (status != RTEMS_SUCCESSFUL)
+      return status;
+
+  status = raspberrypi_gpio_set_pull(gpio->rx, GPIO_PULL_NONE);
+  if (status != RTEMS_SUCCESSFUL)
+      return status;
+
+  status = raspberrypi_gpio_set_pull(gpio->tx, GPIO_PULL_NONE);
+  if (status != RTEMS_SUCCESSFUL)
+      return status;
+
+  return status;
+}
+
+static void output_char(const char ch) {
+  const raspberrypi_console_device* device = &devices[BSP_CONSOLE_PORT];
+  device->write_char_polled(device->context, ch);
+}
+
+static int poll_char(void) {
+  const raspberrypi_console_device* device = &devices[BSP_CONSOLE_PORT];
+  return device->handler->poll_read(device->context);
+}
+
+rtems_status_code raspberrypi_uart_init(
+  raspberrypi_console_device_port uart_num
+)
+{
+  const raspberrypi_console_device *device = &devices[uart_num];
+
+  rtems_status_code status = console_device_init_gpio(&device->gpio);
+  if (status != RTEMS_SUCCESSFUL) {
+    return status;
+  }
+
+  status = rtems_termios_device_install(
+    device->file, device->handler, NULL, device->context
+  );
+  if (status != RTEMS_SUCCESSFUL) {
+    return status;
+  }
+
+  return status;
+}
+
+rtems_device_driver console_initialize(
+  rtems_device_major_number major,
+  rtems_device_minor_number minor,
+  void *arg
+)
+{
+  const raspberrypi_console_device* device = &devices[BSP_CONSOLE_PORT];
+  rtems_status_code status = raspberrypi_uart_init(BSP_CONSOLE_PORT);
+  if (status != RTEMS_SUCCESSFUL) {
+    bsp_fatal(BSP_FATAL_CONSOLE_INSTALL_0);
+  }
+
+  rtems_termios_initialize();
+
+  if (link(device->file, CONSOLE_DEVICE_NAME) != 0) {
+    bsp_fatal(BSP_FATAL_CONSOLE_INSTALL_1);
+  }
+
+  return RTEMS_SUCCESSFUL;
 }
 
 BSP_output_char_function_type BSP_output_char = output_char;
-
-BSP_polling_getchar_function_type BSP_poll_char = NULL;
+BSP_polling_getchar_function_type BSP_poll_char = poll_char;

bsps/aarch64/raspberrypi/include/bsp.h

@@ -62,9 +62,6 @@ extern "C" {
 #define BSP_ARM_GIC_CPUIF_BASE 0xFF842000
 #define BSP_ARM_GIC_DIST_BASE 0xFF841000
 
-#define BSP_RPI4_PL011_BASE 0xFE201000
-#define BSP_RPI4_PL011_LENGTH 0x200
-
 #ifdef __cplusplus
 }
 #endif /* __cplusplus */

bsps/aarch64/raspberrypi/include/bsp/console.h

@@ -0,0 +1,71 @@
+/* SPDX-License-Identifier: BSD-2-Clause */
+
+/**
+ * @file
+ *
+ * @ingroup RTEMSBSPsAArch64RaspberryPi
+ *
+ * @brief Console Configuration
+ */
+
+/*
+ * Copyright (C) 2023 Utkarsh Verma
+ * Copyright (C) 2024 Ning Yang
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions
+ * are met:
+ * 1. Redistributions of source code must retain the above copyright
+ *    notice, this list of conditions and the following disclaimer.
+ * 2. Redistributions in binary form must reproduce the above copyright
+ *    notice, this list of conditions and the following disclaimer in the
+ *    documentation and/or other materials provided with the distribution.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ */
+
+#ifndef LIBBSP_AARCH64_RASPBERRYPI_BSP_CONSOLE_H
+#define LIBBSP_AARCH64_RASPBERRYPI_BSP_CONSOLE_H
+
+#include <bspopts.h>
+#include <bsp/raspberrypi-uart.h>
+
+#define CONSOLE_DEVICES RASPBERRYPI_CONSOLE_DEVICES
+
+#define CONSOLE_DEVICE_PORT2ENUM(port_no) UART##port_no
+#define CONSOLE_DEVICE_ENUM(port_no, ...) CONSOLE_DEVICE_PORT2ENUM(port_no),
+
+typedef enum {
+  CONSOLE_DEVICES(CONSOLE_DEVICE_ENUM)
+  CONSOLE_DEVICE_COUNT,
+} raspberrypi_console_device_port;
+
+/**
+ * @brief Initialize gpio of UART and install UART to the dev directory.
+ *
+ * @param uart_num The optional devices are UART0, UART2, UART3, UART4, UART5.
+ *
+ * @retval RTEMS_SUCCESSFUL Successful operation.
+ * @retval RTEMS_INVALID_NUMBER This status code indicates that a specified
+ *         number was invalid.
+ * @retval RTEMS_NO_MEMORY Not enough memory to create a device node.
+ * @retval RTEMS_UNSATISFIED Creation of the device file failed.
+ * @retval RTEMS_INCORRECT_STATE Termios is not initialized.
+ */
+rtems_status_code raspberrypi_uart_init(
+  raspberrypi_console_device_port uart_num
+);
+
+#undef CONSOLE_DEVICE_ENUM
+
+#endif /* LIBBSP_AARCH64_RASPBERRYPI_BSP_CONSOLE_H */

bsps/aarch64/raspberrypi/include/bsp/raspberrypi-uart.h

@@ -0,0 +1,72 @@
+/* SPDX-License-Identifier: BSD-2-Clause */
+
+/**
+ * @file
+ *
+ * @ingroup RTEMSBSPsAArch64RaspberryPi
+ *
+ * @brief Raspberry Pi 4B Console Device Definitions
+ */
+
+/*
+ * Copyright (C) 2023 Utkarsh Verma
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions
+ * are met:
+ * 1. Redistributions of source code must retain the above copyright
+ *    notice, this list of conditions and the following disclaimer.
+ * 2. Redistributions in binary form must reproduce the above copyright
+ *    notice, this list of conditions and the following disclaimer in the
+ *    documentation and/or other materials provided with the distribution.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ */
+
+#ifndef LIBBSP_AARCH64_RASPBERRYPI_BSP_RASPBERRYPI_UART_H
+#define LIBBSP_AARCH64_RASPBERRYPI_BSP_RASPBERRYPI_UART_H
+
+#include <bspopts.h>
+#include <bsp/irq.h>
+#include <bsp/raspberrypi.h>
+#include <bsp/rpi-gpio.h>
+#include <dev/serial/arm-pl011.h>
+
+/*
+ * This macro exists to serve as a common point of definition for the
+ * parameters of the UARTs present in the Raspberry Pi 4. It is used in
+ * multiple locations with different rendering macros to prevent duplication
+ * of information.
+ */
+#define RASPBERRYPI_CONSOLE_DEVICES(CONSOLE_DEVICE_DEFINITION_RENDERER) \
+    CONSOLE_DEVICE_DEFINITION_RENDERER( \
+      0, "/dev/ttyAMA0", BCM2711_UART0_BASE,BCM2711_UART0_SIZE, \
+      BSP_PL011_CLOCK_FREQ, BCM2711_IRQ_PL011_UART, arm_pl011_context, \
+      &arm_pl011_fns, arm_pl011_write_polled, 15, 14, GPIO_AF0) \
+    CONSOLE_DEVICE_DEFINITION_RENDERER( \
+      2, "/dev/ttyAMA1", BCM2711_UART2_BASE, BCM2711_UART2_SIZE, \
+      BSP_PL011_CLOCK_FREQ, BCM2711_IRQ_PL011_UART, arm_pl011_context, \
+      &arm_pl011_fns, arm_pl011_write_polled, 1, 0, GPIO_AF4) \
+    CONSOLE_DEVICE_DEFINITION_RENDERER( \
+      3, "/dev/ttyAMA2", BCM2711_UART3_BASE, BCM2711_UART3_SIZE, \
+      BSP_PL011_CLOCK_FREQ, BCM2711_IRQ_PL011_UART, arm_pl011_context, \
+      &arm_pl011_fns, arm_pl011_write_polled, 5, 4, GPIO_AF4) \
+    CONSOLE_DEVICE_DEFINITION_RENDERER( \
+      4, "/dev/ttyAMA3", BCM2711_UART4_BASE, BCM2711_UART4_SIZE, \
+      BSP_PL011_CLOCK_FREQ, BCM2711_IRQ_PL011_UART, arm_pl011_context, \
+      &arm_pl011_fns, arm_pl011_write_polled, 9, 8, GPIO_AF4) \
+    CONSOLE_DEVICE_DEFINITION_RENDERER( \
+     5, "/dev/ttyAMA4", BCM2711_UART5_BASE, BCM2711_UART5_SIZE, \
+      BSP_PL011_CLOCK_FREQ, BCM2711_IRQ_PL011_UART, arm_pl011_context, \
+      &arm_pl011_fns, arm_pl011_write_polled, 13, 12, GPIO_AF4)
+#endif /* LIBBSP_AARCH64_RASPBERRYPI_BSP_RASPBERRYPI_UART_H */

bsps/aarch64/raspberrypi/include/bsp/raspberrypi.h

@@ -174,8 +174,25 @@
 
 /** @} */
 
+/**
+ * @name PL011 UARTs
+ *
+ * @{
+ */
+#define BCM2711_PL011_BASE        (RPI_PERIPHERAL_BASE + 0x201000)
+#define BCM2711_PL011_SIZE        0xc00
+#define BCM2711_PL011_DEVICE_SIZE 0x200
 
-
+#define BCM2711_UART0_BASE (BCM2711_PL011_BASE + 0x000)
+#define BCM2711_UART0_SIZE BCM2711_PL011_DEVICE_SIZE
+#define BCM2711_UART2_BASE (BCM2711_PL011_BASE + 0x400)
+#define BCM2711_UART2_SIZE BCM2711_PL011_DEVICE_SIZE
+#define BCM2711_UART3_BASE (BCM2711_PL011_BASE + 0x600)
+#define BCM2711_UART3_SIZE BCM2711_PL011_DEVICE_SIZE
+#define BCM2711_UART4_BASE (BCM2711_PL011_BASE + 0x800)
+#define BCM2711_UART4_SIZE BCM2711_PL011_DEVICE_SIZE
+#define BCM2711_UART5_BASE (BCM2711_PL011_BASE + 0xa00)
+#define BCM2711_UART5_SIZE BCM2711_PL011_DEVICE_SIZE
 /** @} */
 
 /**

spec/build/bsps/aarch64/raspberrypi/bspraspberrypi4.yml

@@ -39,8 +39,6 @@ links:
   uid: ../optgtuseps
 - role: build-dependency
   uid: abi
-- role: build-dependency
-  uid: ../../optconsoleirq
 - role: build-dependency
   uid: ../../optcachedata
 - role: build-dependency
@@ -55,10 +53,10 @@ links:
   uid: ../../dev/irq/objarmgicv2
 - role: build-dependency
   uid: ../../obj
-- role: build-dependency
-  uid: ../../objdevserialarmpl011
 - role: build-dependency
   uid: ../../objirq
+- role: build-dependency
+  uid: objconsole
 - role: build-dependency
   uid: objgpio
 - role: build-dependency
@@ -66,7 +64,6 @@ links:
 - role: build-dependency
   uid: objwatchdog
 source:
-- bsps/aarch64/raspberrypi/console/console.c
 - bsps/aarch64/raspberrypi/start/bspstart.c
 - bsps/aarch64/raspberrypi/start/bspstarthooks.c
 - bsps/aarch64/raspberrypi/start/bspstartmmu.c
@@ -75,8 +72,6 @@ source:
 - bsps/aarch64/shared/mmu/vmsav8-64.c
 - bsps/aarch64/shared/start/start-cpu-mpidr.S
 - bsps/shared/dev/irq/arm-gicv2-get-attributes.c
-- bsps/shared/dev/serial/console-termios-init.c
-- bsps/shared/dev/serial/console-termios.c
 - bsps/shared/dev/getentropy/getentropy-cpucounter.c
 - bsps/shared/dev/btimer/btimer-cpucounter.c
 - bsps/shared/irq/irq-default-handler.c

spec/build/bsps/aarch64/raspberrypi/objconsole.yml

@@ -0,0 +1,30 @@
+SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
+build-type: objects
+cflags: []
+copyrights:
+  - Copyright (C) 2023 Utkarsh Verma
+  - Copyright (C) 2024 Ning Yang
+cppflags: []
+cxxflags: []
+enabled-by: true
+includes: []
+install:
+  - destination: ${BSP_INCLUDEDIR}/bsp
+    source:
+      - bsps/aarch64/raspberrypi/include/bsp/console.h
+  - destination: ${BSP_INCLUDEDIR}/bsp
+    source:
+      - bsps/aarch64/raspberrypi/include/bsp/raspberrypi-uart.h
+links:
+  - role: build-dependency
+    uid: ../../optconsoleirq
+  - role: build-dependency
+    uid: ../../objdevserialarmpl011
+  - role: build-dependency
+    uid: optclockpl011freq
+  - role: build-dependency
+    uid: optconsoleport
+source:
+  - bsps/aarch64/raspberrypi/console/console.c
+  - bsps/shared/dev/serial/console-termios.c
+type: build

spec/build/bsps/aarch64/raspberrypi/optclockpl011freq.yml

@@ -0,0 +1,17 @@
+SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
+actions:
+  - get-integer: null
+  - define: null
+build-type: option
+copyrights:
+  - Copyright (C) 2023 Utkarsh Verma
+default:
+  - enabled-by:
+      - aarch64/raspberrypi4b
+    value: 48000000
+description: PL011 UART clock frequency in Hz.
+enabled-by: true
+format: '{}'
+links: []
+name: BSP_PL011_CLOCK_FREQ
+type: build

spec/build/bsps/aarch64/raspberrypi/optconsoleport.yml

@@ -0,0 +1,23 @@
+SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
+actions:
+  - get-string: null
+  - define-unquoted: null
+  - assert-in-set:
+    - UART0
+    - UART2
+    - UART3
+    - UART4
+    - UART5
+build-type: option
+copyrights:
+  - Copyright (C) 2023 Utkarsh Verma
+default:
+  - enabled-by:
+      - aarch64/raspberrypi4b
+    value: UART0
+description: Default UART port for the console device.
+enabled-by: true
+format: '{}'
+links: []
+name: BSP_CONSOLE_PORT
+type: build