This is an automated email from the ASF dual-hosted git repository.
simbit18 pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/nuttx.git
The following commit(s) were added to refs/heads/master by this push:
new 172dd3959a1 docs/guides/lwl: move lwl's README.txt to lwl.rst
172dd3959a1 is described below
commit 172dd3959a17ae4346ad2d13ccf375d2064f4d7b
Author: Luchian Mihai <[email protected]>
AuthorDate: Mon Dec 22 13:58:09 2025 +0200
docs/guides/lwl: move lwl's README.txt to lwl.rst
This PR moves the lwl's READEME.txt file to Documentation/guides/lwl.rst
Signed-off-by: Luchian Mihai <[email protected]>
---
Documentation/guides/index.rst | 1 +
.../lwl/README.txt => Documentation/guides/lwl.rst | 103 +++++++++++----------
.../user/{13_logging.rst => 14_logging.rst} | 0
3 files changed, 54 insertions(+), 50 deletions(-)
diff --git a/Documentation/guides/index.rst b/Documentation/guides/index.rst
index 677529b6f3e..95457185b80 100644
--- a/Documentation/guides/index.rst
+++ b/Documentation/guides/index.rst
@@ -61,4 +61,5 @@ Guides
rust.rst
optee.rst
qemu_tips.rst
+ lwl.rst
diff --git a/tools/lwl/README.txt b/Documentation/guides/lwl.rst
similarity index 62%
rename from tools/lwl/README.txt
rename to Documentation/guides/lwl.rst
index 8a6fbce2272..02b680801a8 100644
--- a/tools/lwl/README.txt
+++ b/Documentation/guides/lwl.rst
@@ -1,15 +1,16 @@
+=============================
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
+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.
@@ -25,7 +26,8 @@ upwordaddr if you want to work with fixed locations.
Bit configuration
-----------------
-Downword (Host to target);
+Downword (Host to target)
+^^^^^^^^^^^^^^^^^^^^^^^^^
A D U VV XXX O2 O1 O0
@@ -38,7 +40,8 @@ O2 23-16 8 - Octet 2
O1 15-08 8 - Octet 1
O0 07-00 8 - Octet 0
-Upword (Target to Host);
+Upword (Target to Host)
+^^^^^^^^^^^^^^^^^^^^^^^
A 31 1 - Service Active (Set by device)
D 30 1 - Downsense ack (Toggled to acknowledge receipt of downlink data)
@@ -61,55 +64,55 @@ 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:
-------------------------------------------
-$ 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
-...
-
-The "0x2000000c:..." will repeat all the time.
+.. 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:
-------------------------------------------
-$ ./ocdconsole.py
-==Link Activated
-
-nsh>
-nsh> help
-help usage: help [-v] [<cmd>]
+.. code-block:: console
- ? echo exit hexdump ls mh sleep xd
- cat exec help kill mb mw usleep
-nsh>
-------------------------------------------
+ $ ./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
+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
@@ -124,4 +127,4 @@ 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.
+``nuttx/arch/arm/src/common/arm_lwl_console.c`` for more information.
diff --git a/Documentation/reference/user/13_logging.rst
b/Documentation/reference/user/14_logging.rst
similarity index 100%
rename from Documentation/reference/user/13_logging.rst
rename to Documentation/reference/user/14_logging.rst
