This is an automated email from the ASF dual-hosted git repository.

casaroli pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/nuttx.git

commit 846f9ac992e755cba44347863119737182ef7003
Author: Alan Carvalho de Assis <[email protected]>
AuthorDate: Tue Nov 10 16:29:48 2026 -0300

    Documentation: Rewrite the Lightweight Link (LWL) console guide.
    
    Document the interrupt driven LWL console: quick start, configuration
    options, doorbell and polling, the control block, the word format, the
    input handshake, the output ring buffer and word protocols, opening and
    closing the link, buffering, flow control and prompt replay, the host
    terminal and its compatibility with older firmware, how to write a host
    for another debugger, measured performance and troubleshooting.
    
    Describe the weact-stm32h743:lwl configuration and remove the outdated
    arch/arm/src/common/README_lwl_console.txt, now covered by the guide.
    
    Signed-off-by: Alan Carvalho de Assis <[email protected]>
    Assisted-by: Claude Code Opus 5.5
---
 Documentation/guides/drivers/lwl.rst               | 533 ++++++++++++++++-----
 .../arm/stm32h7/boards/weact-stm32h743/index.rst   |  24 +
 arch/arm/src/common/README_lwl_console.txt         |  59 ---
 3 files changed, 442 insertions(+), 174 deletions(-)

diff --git a/Documentation/guides/drivers/lwl.rst 
b/Documentation/guides/drivers/lwl.rst
index 02b680801a8..c129f90759a 100644
--- a/Documentation/guides/drivers/lwl.rst
+++ b/Documentation/guides/drivers/lwl.rst
@@ -1,130 +1,433 @@
-=============================
-Console over Lightweight Link
-=============================
-
-LWL is a Lightweight bidirectional communication between target and debug host
-without any need for additional hardware.
- 
-It works with openOCD and other debuggers that are capable of reading and
-writing memory while the target is running...it should run with JLink
-for example, if you've got the SDK and modify this file accordingly.
-
-Principle of operation is simple; An `'upword'` of 32 bits communicates
-from the target to the host, a `'downword'` of the same size runs in the
-opposite direction. These two words can be in any memory that is
-read/write access for both the target and the debug host. A simple ping
-pong handshake protocol over these words allows up/down link communication.
-On the upside no additional integration is needed. On the downside it may be
-necessary to feed lwl with cycles to poll for changes in the downword,
-depending on the use case. For the case of a simple console, that's not
-needed.
-
-For convenience these communication locations are automatically discovered
-from the RAM by searching through it. Just define downwordaddr and
-upwordaddr if you want to work with fixed locations.
-
-Bit configuration
------------------
+===================================
+Console over Lightweight Link (LWL)
+===================================
 
-Downword (Host to target)
-^^^^^^^^^^^^^^^^^^^^^^^^^
+The Lightweight Link (LWL) gives a target a NuttShell console, or any
+other console traffic, through the debug probe that is already connected
+to it.  It needs no UART, no USB and no extra pin: the target and the host
+exchange data through two words of target RAM that the debugger reads and
+writes while the CPU is running.
 
-A D U VV XXX O2 O1 O0
+It is useful when the board has no spare serial port, during the bring-up
+of a new chip, or when the only connection to the board is the SWD/JTAG
+probe.  Unlike semihosting it never halts the CPU, so the target keeps its
+real-time behaviour, and unlike SWO it works in both directions.
 
-A   31    1 - Service Active (Set by host)
-D   30    1 - Downsense (Toggled when there is data)
-U   29    1 - Upsense ack (Toggled to acknowledge receipt of uplink data)
-VV  28-27 2 - Valid Octets (Number of octets valid in the message)
-XXX 26-24 3 - Port in use (Type of the message)
-O2  23-16 8 - Octet 2
-O1  15-08 8 - Octet 1
-O0  07-00 8 - Octet 0
+Any debugger that can access memory while the target runs can be used.  The
+host side terminal shipped with NuttX, ``tools/lwl/ocdconsole.py``, uses
+OpenOCD.
 
-Upword (Target to Host)
-^^^^^^^^^^^^^^^^^^^^^^^
+.. contents::
+   :local:
+   :depth: 2
 
-A   31    1 - Service Active (Set by device)
-D   30    1 - Downsense ack (Toggled to acknowledge receipt of downlink data)
-U   29    1 - Upsense (Toggled when there is data)
-VV  28-27 2 - Valid upword octets
-XXX 26-24 3 - Port in use (Type of the message)
-O2  23-16 8 - Octet 2
-O1  15-08 8 - Octet 1
-O0  07-00 8 - Octet 0
+Quick start
+===========
 
-Port 1 is used for Console. No other ports are currently defined.
+The ``weact-stm32h743:lwl`` configuration is a ready to use example.  Build
+and flash it with the ST-Link connected to the SWD pins of the board:
 
-Usage
-=====
+.. code-block:: console
 
-No special python modules are needed, it should be possible to run the
-application simply as shown below:
+   $ ./tools/configure.sh weact-stm32h743:lwl
+   $ make
+   $ openocd -f interface/stlink.cfg -f target/stm32h7x.cfg \
+       -c "program nuttx.bin 0x08000000 verify reset exit"
 
-In the first terminal execute the openocd command to connect to the board.
-Assuming that you already flashed to firmware (nuttx.bin) with the LWL
-console support. For stm32f4discovery board I use this command:
+Leave OpenOCD running:
 
 .. code-block:: console
 
-  $ sudo openocd -f board/stm32f4discovery.cfg
-  Open On-Chip Debugger  v0.10.0-esp32-20200526-6-g4c41a632 (2020-06-23-10:12)
-  Licensed under GNU GPL v2
-  For bug reports, read
-       http://openocd.org/doc/doxygen/bugs.html
-  Info : The selected transport took over low-level target control. The 
results might differ compared to plain JTAG/SWD
-  srst_only separate srst_nogate srst_open_drain connect_deassert_srst
-  
-  Info : Listening on port 6666 for tcl connections
-  Info : Listening on port 4444 for telnet connections
-  Info : clock speed 2000 kHz
-  Info : STLINK V2J17S0 (API v2) VID:PID 0483:3748
-  Info : Target voltage: 3.216252
-  Info : stm32f4x.cpu: hardware has 6 breakpoints, 4 watchpoints
-  Info : Listening on port 3333 for gdb connections
-  Info : accepting 'tcl' connection on tcp/6666
-  invalid command name "ocd_mdw"
-  0x20000000: 000000ff
-
-  0x20000000: 000000ff
-  
-  0x20000004: 7216a318
-  
-  0x2000000c: 994b5b1b
-  
-  0x2000000c: 994b5b1b
-  
-  0x2000000c: 994b5b1b
-
-  ...
-
-Now in another terminal execute:
+   $ openocd -f interface/stlink.cfg -f target/stm32h7x.cfg
+
+and start the terminal in another shell:
+
+.. code-block:: console
+
+   $ ./tools/lwl/ocdconsole.py --elf nuttx
+   ==Link Activated
+
+   NuttShell (NSH)
+   nsh> ps
+     TID   PID  PPID PRI POLICY   TYPE    NPX STATE    EVENT     SIGMASK       
     STACK    CPU COMMAND
+       0     0     0   0 FIFO     Kthread   - Ready              
0000000000000000 0001000 100.0% Idle_Task
+       2     2     0 100 RR       Task      - Running            
0000000000000000 0003024   0.0% nsh_main
+   nsh>
+
+Press ``Ctrl-]`` to leave the terminal.  All the other keys, ``Ctrl-C``
+included, are sent to the target.
+
+Enabling LWL on a board
+=======================
+
+LWL is a console driver, so it replaces the serial console:
+
+* Disable the serial console of the board (e.g. 
``CONFIG_USART1_SERIAL_CONSOLE``).
+* Enable ``CONFIG_LWL_CONSOLE``.  It requires an architecture that selects
+  ``ARCH_HAVE_RDWR_MEM_CPU_RUN`` (ARM, ARM64 and RISC-V today).
+* If the debugger can make an interrupt pending by writing a register of
+  the interrupt controller, enable ``CONFIG_LWL_CONSOLE_DOORBELL`` and pick
+  an interrupt for it, see `Doorbell interrupt`_.
+
+The driver registers itself as ``/dev/console``.  It is a lower half of the
+generic serial driver, so the console behaves like any other NuttX TTY:
+buffered I/O, ``termios`` processing (``ECHO``, ``ICRNL``, ``ONLCR``, ...),
+``poll()``/``select()`` and the TTY signals all work.  ``up_putc()`` is
+provided as well, so ``syslog`` and crash dumps also go to the host.
+
+Configuration options
+---------------------
+
+===================================== ========================================
+Option                                Description
+===================================== ========================================
+``CONFIG_LWL_CONSOLE``                Enable the LWL console.
+``CONFIG_LWL_CONSOLE_RXBUFSIZE``      Size of the buffer holding the input
+                                      until the application reads it (default
+                                      64).
+``CONFIG_LWL_CONSOLE_TXBUFSIZE``      Size of the buffer holding the output
+                                      until the host collects it (default
+                                      256).
+``CONFIG_LWL_CONSOLE_RINGSIZE``       Size of the ring buffer from which the
+                                      host collects the output (default 256, a
+                                      multiple of 4).  ``0`` limits the output
+                                      to the slow word protocol.
+``CONFIG_LWL_CONSOLE_DOORBELL``       Let the host raise an interrupt when it
+                                      updates the link.
+``CONFIG_LWL_CONSOLE_DOORBELL_IRQ``   The NuttX IRQ number used as doorbell.
+``CONFIG_LWL_CONSOLE_DOORBELL_ADDR``  Address of the register the host writes
+                                      to make that IRQ pending.
+``CONFIG_LWL_CONSOLE_DOORBELL_VALUE`` Value the host writes to that register.
+``CONFIG_LWL_CONSOLE_POLL_INTERVAL``  Without the doorbell, interval in
+                                      microseconds at which the link is
+                                      polled (default 10000).
+===================================== ========================================
+
+Doorbell interrupt
+------------------
+
+Most interrupt controllers have a register that makes an interrupt
+pending when it is written, exactly as if the peripheral had raised it, and
+the debugger can write it while the CPU runs.  LWL uses this as a doorbell:
+after every update of the link the host rings it, the target handles the
+new data in the interrupt handler and goes back to sleep.  There is no
+polling and no busy waiting at all, the console costs no CPU time while it
+is idle.
+
+The board configuration gives three values:
+
+* ``CONFIG_LWL_CONSOLE_DOORBELL_IRQ``: the NuttX IRQ number of an
+  interrupt that is implemented by the chip but not used by any driver of
+  the configuration.  A good candidate is the interrupt of a peripheral
+  that is not enabled.
+* ``CONFIG_LWL_CONSOLE_DOORBELL_ADDR``: the register the host writes to make
+  that interrupt pending.
+* ``CONFIG_LWL_CONSOLE_DOORBELL_VALUE``: the value the host writes there.
+
+The interrupt handler writes 0 to the register before it services the
+link.  This clears level-type software interrupts and has no effect on
+set-pending registers, so the register must be one of the two.
+
+The firmware publishes the address and the value in the control block, so
+the host does not need to know the chip.  With the doorbell the link is
+not polled at all, so the host must ring it: ``ocdconsole.py`` does, older
+terminals that don't need a firmware built without the doorbell.
+
+Interrupt controllers that fit:
+
+.. list-table::
+   :header-rows: 1
+
+   * - Controller
+     - ``DOORBELL_ADDR``
+     - ``DOORBELL_VALUE``
+   * - ARMv6/7/8-M NVIC
+     - Interrupt Set-Pending Register,
+       ``0xe000e200 + 4 * ((IRQ - 16) / 32)``
+     - ``1 << ((IRQ - 16) % 32)``
+   * - ARM GIC
+     - ``GICD_ISPENDR<n>`` of a shared peripheral interrupt,
+       ``n = INTID / 32``
+     - ``1 << (INTID % 32)``
+   * - RISC-V CLINT
+     - ``msip`` register of the hart (machine software interrupt)
+     - ``1``
+
+Only the NVIC has been tested.  For instance ``weact-stm32h743:lwl`` uses
+IRQ 160, ``STM32_IRQ_CRS`` (the Clock Recovery System, which NuttX does not
+use on STM32H7): external interrupt 144, so the register is ``0xe000e210``
+and the value ``0x10000``.
+
+On RISC-V the debugger can only access memory while the hart runs if the
+debug module implements System Bus Access, which is optional, and the CLINT
+software interrupt must not be used for something else (e.g. SMP
+inter-processor interrupts).
+
+Polling
+-------
+
+Without the doorbell (no suitable interrupt, a host tool that does not
+ring it, a debugger that cannot write the interrupt controller) the driver
+polls the link with a watchdog timer every
+``CONFIG_LWL_CONSOLE_POLL_INTERVAL`` microseconds.
+Each poll refills the output ring buffer, or moves one word with hosts that
+don't use it, so the throughput depends on the interval: about 7 KB/s with
+the ring and 300 bytes/s without it for the default 10 ms.
+
+Polling runs while the console is open, whether a host is connected or
+not, so the CPU wakes up at this rate.  Polling works with any host.
+
+How it works
+============
+
+The control block
+-----------------
+
+The target and the host share a control block in target RAM, the
+``g_lwl`` variable of ``drivers/misc/lwl_console.c``.  The host finds it from
+the ELF symbol table or by searching the signature in RAM.
+
+====== ============ =========================================================
+Offset Field        Description
+====== ============ =========================================================
+0x00   ``sig``      ``0x7216a318``, lets the host find the block.
+0x04   ``downword`` Host to target data, written by the host.
+0x08   ``upword``   Target to host data, written by the target (word
+                    protocol only).
+0x0c   ``extsig``   ``0x4c574c32`` ("LWL2") if the fields below are valid.
+                    Firmware older than this version does not have this
+                    field nor the next ones.
+0x10   ``dbaddr``   Address the host writes to ring the doorbell, 0 if there
+                    is no doorbell.
+0x14   ``dbval``    Value the host writes to ``dbaddr``.
+0x18   ``ringsize`` Size of the output ring buffer, 0 if there is none.
+0x40   ``hostcaps`` Written by the host before it opens the link.  Bit 0:
+                    the host reads the ring buffer.
+0x44   ``uptail``   Written by the host: offset in ``ring`` of the next octet
+                    it will read.
+0x80   ``status``   Written by the target: its ``A`` and ``D`` bits (ring
+                    protocol only).
+0x84   ``uphead``   Written by the target: offset in ``ring`` of the next
+                    octet it will write.
+0xc0   ``ring``     Output ring buffer of ``ringsize`` octets, written by
+                    the target.
+====== ============ =========================================================
+
+The debugger accesses the memory behind the data cache of the CPU, so on
+targets with a data cache the driver cleans what it writes and invalidates
+what the host writes.  The block is aligned to 64 bytes and the fields
+written by the host (0x00-0x7f) and by the target (0x80 and above) are in
+different 64 byte groups: cleaning a cache line never writes a stale copy
+of a host field back to RAM.  The legacy ``upword`` is the exception, so
+with a write-back data cache use a host that reads the ring buffer.
+
+Word format
+-----------
+
+The downword, the upword and the status word share the same format::
+
+   31  30  29  28-27  26-24  23-16  15-8  7-0
+   A   D   U   VV     XXX    O2     O1    O0
+
+===== ===== ================================ ================================
+Bits  Name  Downword (host to target)        Upword/status (target to host)
+===== ===== ================================ ================================
+31    A     Link active, set by the host     Link active, set by the target
+30    D     Downsense: toggled when the      Downsense ack: copied from the
+            word carries new data            downword once it is consumed
+29    U     Upsense ack: copied from the     Upsense: toggled when the word
+            upword once it is consumed       carries new data (upword only)
+28-27 VV    Number of valid octets, 0 to 3   Number of valid octets, 0 to 3
+26-24 XXX   Port, 1 is the console           Port, 1 is the console
+23-0  O2-O0 Data octets, O0 in bits 7-0      Data octets, O0 in bits 7-0
+===== ===== ================================ ================================
+
+Input: the downword
+-------------------
+
+The input always goes through the downword, with a ping-pong handshake on
+the ``D`` bit.  The host may write a new downword only when the ``D`` bit
+reported by the target equals the ``D`` bit of its last downword, i.e. the
+target consumed the previous one.  It then writes up to three octets, their
+number and the port with the ``D`` bit toggled, and rings the doorbell.  The
+target copies the octets into its RX buffer and acknowledges by copying
+``D`` into the status word (or the upword with the word protocol).
+
+Output: the ring buffer
+-----------------------
+
+Hosts that set bit 0 of ``hostcaps`` collect the output from the ring
+buffer.  The target copies the output to ``ring`` at ``uphead`` and
+advances ``uphead``, as long as it does not reach ``uptail`` (one octet
+always stays free, ``uphead == uptail`` means empty).  The host reads
+``status``, ``uphead`` and ``ring`` in a single memory access, outputs the
+octets from ``uptail`` to ``uphead``, writes the new ``uptail`` and rings the
+doorbell, so the target refills the ring.  A whole ring of output costs one
+round trip instead of one per three octets.
+
+Output: the word protocol
+-------------------------
+
+Older hosts collect the output from the upword, with a ping-pong handshake
+on the ``U`` bit.  The target writes a new upword with up to three octets
+and the ``U`` bit toggled only when the ``U`` bit of the downword equals its
+own, i.e. the host collected the previous one.  The host outputs the
+octets, acknowledges by copying ``U`` into the downword and rings the
+doorbell.  This is also what the target uses when ``ringsize`` is 0.
+
+Opening and closing the link
+----------------------------
+
+The host opens the link by setting ``A`` in the downword, after it wrote
+``hostcaps`` and ``uptail``.  When the target sees it, it selects the ring
+or the word protocol from ``hostcaps``, sets ``A`` in the status word (or
+the upword), adopts the host's ``D`` and ``U`` bits and sets ``uphead`` to
+``uptail``: there is neither pending input nor stale output whatever the
+state of a previous session.
+
+The host closes the link by writing 0 to the downword.  The target answers
+with a status word and an upword of 0.
+``ocdconsole.py`` always closes the link before opening it, which
+resynchronises the target even if the previous host was killed without
+closing the link.
+
+Buffering and flow control
+--------------------------
+
+* The application writes into the TX buffer and returns; the driver moves
+  the data to the ring buffer (or the upword) as the host collects it.
+  When the buffer is full the writer blocks until the host collects data,
+  as with a UART.
+* Received octets are stored in the RX buffer.  When it is full the driver
+  leaves the downword unacknowledged, which holds off the host until the
+  application reads: no input is lost, even when pasting text into a busy
+  shell.  The host re-rings the doorbell while its data is pending.
+* While no host is connected, writers never block: the TX buffer keeps the
+  most recent output, dropping the oldest data, and it is shown when a host
+  connects.  For instance the boot banner appears as soon as the terminal
+  is started.
+* The driver remembers the line being output (up to 80 octets since the
+  last newline, typically the ``nsh>`` prompt and what was typed after it)
+  and sends it again to every new host, so the prompt is there without
+  pressing Enter even if a previous host already collected it.
+* ``up_putc()`` (syslog, crash dumps) writes directly to the link and
+  busy-waits for room.  If an open link is not served for a long time
+  (the host was killed without closing it) it starts dropping characters
+  instead of hanging the system.
+
+The host terminal
+=================
+
+``tools/lwl/ocdconsole.py`` connects to the TCL RPC server of OpenOCD
+(port 6666) and needs nothing but the Python 3 standard library.  It uses
+``read_memory`` when OpenOCD provides it (0.12 and later) and falls back to
+``mdw`` otherwise.
 
 .. code-block:: console
 
-  $ ./ocdconsole.py
-  ==Link Activated
-  
-  nsh>
-  nsh> help
-  help usage:  help [-v] [<cmd>]
-  
-   ?        echo     exit     hexdump  ls       mh       sleep    xd
-   cat      exec     help     kill     mb       mw       usleep
-  nsh>
-
-This code is designed to be `'hardy'` and will survive a shutdown and
-restart of the openocd process. When your target application
-changes then the location of the upword and downword may change,
-so they are re-searched for again. To speed up the start process
-consider putting those words at fixed locations (e.g. via the
-linker file) and referencing them directly.
-
-Future work/Improvements
-========================
-
-Currently the lwl driver on NuttX side is doing polling, but for
-better performance it could use interrupts to detect when the memory
-position was modified to read the data.
-
-It also will avoid using busy waiting inside the driver, look at
-``nuttx/arch/arm/src/common/arm_lwl_console.c`` for more information.
+   $ ./tools/lwl/ocdconsole.py --help
+   usage: ocdconsole.py [-h] [--host HOST] [--port PORT]
+                        [--elf ELF | --addr ADDR | --scan BASE:LEN] [-v]
+
+====================== =====================================================
+Option                 Description
+====================== =====================================================
+``--elf nuttx``        Take the address of the control block from the ELF
+                       file of the running firmware.  Fastest and most
+                       reliable.
+``--addr 0x24000040``  Use the given control block address.
+``--scan BASE:LEN``    Search the signature in these RAM ranges (can be
+                       repeated).  By default the first 64 KiB at
+                       ``0x20000000`` and at ``0x24000000`` are searched.
+``--host``, ``--port`` OpenOCD TCL RPC server, ``127.0.0.1:6666`` by default.
+``-v``                 Print where the control block is, the protocol used
+                       and whether the doorbell is used.
+====================== =====================================================
+
+The terminal survives restarts of OpenOCD and of the target: it reconnects
+and reopens the link.
+
+Compatibility
+-------------
+
+The word protocol did not change, so old and new versions interoperate:
+
+* The new terminal with old firmware: the missing ``extsig`` tells the
+  terminal to use the word protocol, send one octet per word, translate the
+  line endings, skip the doorbell and leave the link open on exit (old
+  firmware ends the shell session when the link closes).
+* An old terminal with new firmware built without the doorbell: the
+  firmware uses the word protocol and polls the link.  The old terminal
+  does not wait for the acknowledge before sending the next key, so fast
+  typing or pasting may lose characters.  Old terminals don't ring the
+  doorbell, so they don't work with firmware built with it.
+
+Writing a host for another debugger
+-----------------------------------
+
+Any tool that can read and write target memory while the target runs can
+be a host.  The loop of ``ocdconsole.py`` is a good reference:
+
+#. Find the control block and read ``extsig``, ``dbaddr``, ``dbval`` and
+   ``ringsize``.
+#. Write 0 to the downword, ring the doorbell and wait until both the
+   upword and the status word read 0.
+#. Write 1 to ``hostcaps`` and 0 to ``uptail``, write ``A`` to the
+   downword and ring until the status word has ``A``.
+#. Read ``status``, ``uphead`` and ``ring`` (from offset 0x80, in one
+   access).  If ``uphead`` differs from ``uptail``, output the octets in
+   between and write ``uphead`` to ``uptail``.
+#. If the ``D`` bits of the status word and of the downword are equal and
+   there is input, put up to three octets in the downword and toggle its
+   ``D`` bit.
+#. If something was written, ring the doorbell.  Go to 4.
+#. On exit write 0 to the downword and to ``hostcaps`` and ring the
+   doorbell.
+
+Performance
+===========
+
+Measured on the WeAct STM32H743 (480 MHz Cortex-M7) with an ST-Link/V2 and
+OpenOCD 0.12, writing to the console with ``dd``:
+
+======================================= ================= ==================
+                                        Previous driver   Current driver
+======================================= ================= ==================
+CPU used by ``nsh`` waiting for input   100 %             0 %
+Output throughput                       ~1.8 KB/s         ~28 KB/s
+Input buffering                         none              RX buffer, host
+                                                          held off when full
+Output while no host is connected       writer hangs      last 256 bytes kept
+Prompt shown when a host connects       no                yes
+Data cache enabled (D-cache on STM32H7) does not work     works
+======================================= ================= ==================
+
+For reference a UART at 115200 baud moves about 11 KB/s.  The throughput is
+bounded by the round trip time between the terminal, OpenOCD and the probe,
+so a larger ring helps a little (about 39 KB/s with
+``CONFIG_LWL_CONSOLE_RINGSIZE=1024``).  With the word protocol every three
+octets cost a round trip: about 1.3 KB/s with the doorbell and 300 bytes/s
+when polled.
+
+Troubleshooting
+===============
+
+``==Waiting for the target`` repeats forever
+   The firmware does not answer.  Check that it runs (it may have crashed
+   before opening the console), that the control block address is right
+   (use ``--elf`` with the ELF file that is actually flashed) and, with the
+   doorbell, that the terminal rings it (``-v`` shows ``doorbell at ...``).
+
+``Cannot find the LWL signature``
+   The control block is outside of the default search ranges.  Use
+   ``--elf`` or ``--scan`` with the RAM of your chip.
+
+``LWL signature found at 0x20000af8, 0x24000040, ...``
+   RAM keeps its content across resets, so a previous firmware may have
+   left a stale copy of the control block.  The terminal does not guess,
+   since writing to the wrong place could corrupt the target: use ``--elf``
+   or ``--addr``.
+
+Nothing happens on the target when the doorbell is rung
+   The doorbell IRQ is not implemented by the chip, or another driver
+   attached the same interrupt.  Pick another one.
diff --git 
a/Documentation/platforms/arm/stm32h7/boards/weact-stm32h743/index.rst 
b/Documentation/platforms/arm/stm32h7/boards/weact-stm32h743/index.rst
index dea736781b9..3b371720bd7 100644
--- a/Documentation/platforms/arm/stm32h7/boards/weact-stm32h743/index.rst
+++ b/Documentation/platforms/arm/stm32h7/boards/weact-stm32h743/index.rst
@@ -231,6 +231,30 @@ After flashing and reboot your board you should see in 
your dmesg logs::
 
 You may need to press **ENTER** 3 times before the NSH show up.
 
+lwl
+---
+
+Configures the NuttShell (nsh) with the console over the Lightweight Link
+(LWL): the console goes through the SWD probe (e.g. STLink-V2) instead of a
+UART, so only the SWD wires are needed. The host raises the CRS interrupt
+(IRQ 160, unused by NuttX) as a doorbell, so the console uses no CPU time
+while it is idle.
+
+Flash the board as described in `SWD`_, leave OpenOCD running::
+
+    $ openocd -f interface/stlink.cfg -f target/stm32h7x.cfg
+
+and start the terminal in another shell::
+
+    $ ./tools/lwl/ocdconsole.py --elf nuttx
+    ==Link Activated
+
+    NuttShell (NSH)
+    nsh>
+
+Press ``Ctrl-]`` to quit the terminal. See :doc:`/guides/drivers/lwl` for
+details.
+
 sdcard
 ------
 
diff --git a/arch/arm/src/common/README_lwl_console.txt 
b/arch/arm/src/common/README_lwl_console.txt
deleted file mode 100644
index 266cd4f4d45..00000000000
--- a/arch/arm/src/common/README_lwl_console.txt
+++ /dev/null
@@ -1,59 +0,0 @@
-The file arm_lwl_console.c implements a 'Lightweight Link' protocol between
-a target and debugger for use when you need a console but the target doesn't
-have a spare serial port or other available resource. This implements a
-new console type which uses two words of memory for data exchange.
-
-It is not particularly efficient because of the various compromises that are
-made (polling in busy loops, mostly) but it works well enough to give you
-something where you previously had nothing...typically the case when you're
-bring up a new CPU, or when the hardware designer thought the softies could
-cope without a logging port. It has an advantage over semi-hosting in that
-it doesn't put the target into debug mode while it's running, so you've got
-some hope of maintaining real time semantics.  To be clear, for output only
-use you'd be better off with SWO if you've got it available!
-
-There is a terminal program in python(*) for the host side in
-tools/ocdconsole.py for use with openocd...the NuttX side functionality is
-not dependent on a specific debugger, the only requirement on it being that
-the debugger can watch and modify a memory location on the target while it is 
executing.
-
-Typical use is;
-
-$ tools/ocdconsole.py
-==Link Activated
-
-NuttShell (NSH)
-nsh> help
-help usage:  help [-v] [<cmd>]
-
-  ?        echo     exit     hexdump  ls       mh sleep    xd
-  cat      exec     help     kill     mb       mw usleep
-nsh>
-
-On the target side it's transparent, and is just a console;
-
-nsh> ls /dev
-/dev:
- console
- null
- ttyS0
-nsh> echo "Hello World" > /dev/console
-Hello World
-nsh>
-
-CPU load on the host is surprisingly low given that the polling loop is
-continuous (probably due to the fact that openocd is spending most of it's
-time waiting for messages to/from the debug port on the target). When not
-actively doing anything there's no load on the target, but waiting for input
-is done in a busy polled loop (so the thread is effectively busy-locked)
-and output busy-waits for the previous message to be collected before it
-sends the next one.
-
-For now I've only made it available on stm32, but it should only be a case
-of changing the Kconfig and Make.defs for other arm CPUs to make it
-available for them too. Moving beyond arm needs knowledge of the targets
-that I don't have.
-
-If anyone fancies extending this proof-of-concept to full Segger-RTT-style
-functionality then drop me a note, there are plenty of ways to improve
-performance.

Reply via email to