[RFC PATCH 0/2] doc: sphinx: Add sphinx-prompt
Add Sphinx-prompt for more readable documentation and yet is userfriendly for people to copy paste.
See https://lore.kernel.org/all/87fs48rgto.fsf@baylibre.com/
If this approach looks correct, please ack and I can convert the doc/board/ti/*.rst segments off to prompt instead of code-block where applicable.
Quick video to show the difference in experience: https://youtu.be/ylDrHXWGVgo
Nishanth Menon (2): doc: sphinx: Add sphinx-prompt doc: board: ti: k3: Convert to sphinx-prompt
doc/board/ti/k3.rst | 112 ++++++++++++++++++------------------ doc/conf.py | 2 +- doc/sphinx/requirements.txt | 1 + 3 files changed, 59 insertions(+), 56 deletions(-)
Sphinx-prompt[1] helps bring-in '.. prompt::' option that allows a better rendered documentation, yet be able to copy paste without picking up the prompt from rendered documentation.
[1] https://lore.kernel.org/all/87fs48rgto.fsf@baylibre.com/ Suggested-by: Mattijs Korpershoek mkorpershoek@baylibre.com Signed-off-by: Nishanth Menon nm@ti.com --- Version picked is the best that works with Sphinx 3.4.3
doc/conf.py | 2 +- doc/sphinx/requirements.txt | 1 + 2 files changed, 2 insertions(+), 1 deletion(-)
diff --git a/doc/conf.py b/doc/conf.py index 00f241366477..5e2ff1c8f5e2 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -39,7 +39,7 @@ needs_sphinx = '2.4.4' extensions = ['kerneldoc', 'rstFlatTable', 'kernel_include', 'kfigure', 'sphinx.ext.ifconfig', # 'automarkup', 'maintainers_include', 'sphinx.ext.autosectionlabel', - 'kernel_abi', 'kernel_feat'] + 'kernel_abi', 'kernel_feat', 'sphinx-prompt']
# # cdomain is badly broken in Sphinx 3+. Leaving it out generates *most* diff --git a/doc/sphinx/requirements.txt b/doc/sphinx/requirements.txt index 4f411f78d030..6ccbe527ee79 100644 --- a/doc/sphinx/requirements.txt +++ b/doc/sphinx/requirements.txt @@ -15,6 +15,7 @@ requests==2.31.0 six==1.16.0 snowballstemmer==2.2.0 Sphinx==3.4.3 +sphinx-prompt==1.5.0 sphinx-rtd-theme==1.0.0 sphinxcontrib-applehelp==1.0.2 sphinxcontrib-devhelp==1.0.2
On 24.08.23 17:40, Nishanth Menon wrote:
Sphinx-prompt[1] helps bring-in '.. prompt::' option that allows a better rendered documentation, yet be able to copy paste without picking up the prompt from rendered documentation.
[1] https://lore.kernel.org/all/87fs48rgto.fsf@baylibre.com/ Suggested-by: Mattijs Korpershoek mkorpershoek@baylibre.com Signed-off-by: Nishanth Menon nm@ti.com
Looks good to me.
Version picked is the best that works with Sphinx 3.4.3
doc/conf.py | 2 +- doc/sphinx/requirements.txt | 1 + 2 files changed, 2 insertions(+), 1 deletion(-)
diff --git a/doc/conf.py b/doc/conf.py index 00f241366477..5e2ff1c8f5e2 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -39,7 +39,7 @@ needs_sphinx = '2.4.4' extensions = ['kerneldoc', 'rstFlatTable', 'kernel_include', 'kfigure', 'sphinx.ext.ifconfig', # 'automarkup', 'maintainers_include', 'sphinx.ext.autosectionlabel',
'kernel_abi', 'kernel_feat']
'kernel_abi', 'kernel_feat', 'sphinx-prompt']
We copied our conf.py from kernel.org. Please, check if it can be added upstream.
/linux$ scripts/get_maintainer.pl Documentation/conf.py Jonathan Corbet corbet@lwn.net (maintainer:DOCUMENTATION) linux-doc@vger.kernel.org (open list:DOCUMENTATION) linux-kernel@vger.kernel.org (open list) bpf@vger.kernel.org (open list:BPF [MISC])
Does the extension exist on their minimum Sphinx version (1.7) or at least on the 2.24 in Documentation/requirements.txt?
Best regards
Heinrich
# # cdomain is badly broken in Sphinx 3+. Leaving it out generates *most* diff --git a/doc/sphinx/requirements.txt b/doc/sphinx/requirements.txt index 4f411f78d030..6ccbe527ee79 100644 --- a/doc/sphinx/requirements.txt +++ b/doc/sphinx/requirements.txt @@ -15,6 +15,7 @@ requests==2.31.0 six==1.16.0 snowballstemmer==2.2.0 Sphinx==3.4.3 +sphinx-prompt==1.5.0 sphinx-rtd-theme==1.0.0 sphinxcontrib-applehelp==1.0.2 sphinxcontrib-devhelp==1.0.2
On 17:47-20230824, Heinrich Schuchardt wrote:
On 24.08.23 17:40, Nishanth Menon wrote:
Sphinx-prompt[1] helps bring-in '.. prompt::' option that allows a better rendered documentation, yet be able to copy paste without picking up the prompt from rendered documentation.
[1] https://lore.kernel.org/all/87fs48rgto.fsf@baylibre.com/ Suggested-by: Mattijs Korpershoek mkorpershoek@baylibre.com Signed-off-by: Nishanth Menon nm@ti.com
Looks good to me.
Version picked is the best that works with Sphinx 3.4.3
doc/conf.py | 2 +- doc/sphinx/requirements.txt | 1 + 2 files changed, 2 insertions(+), 1 deletion(-)
diff --git a/doc/conf.py b/doc/conf.py index 00f241366477..5e2ff1c8f5e2 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -39,7 +39,7 @@ needs_sphinx = '2.4.4' extensions = ['kerneldoc', 'rstFlatTable', 'kernel_include', 'kfigure', 'sphinx.ext.ifconfig', # 'automarkup', 'maintainers_include', 'sphinx.ext.autosectionlabel',
'kernel_abi', 'kernel_feat']
'kernel_abi', 'kernel_feat', 'sphinx-prompt']We copied our conf.py from kernel.org. Please, check if it can be added upstream.
https://git.kernel.org/pub/scm/linux/kernel/git/ti/linux.git/tree/Documentat...
Looks pretty different though :(
/linux$ scripts/get_maintainer.pl Documentation/conf.py Jonathan Corbet corbet@lwn.net (maintainer:DOCUMENTATION) linux-doc@vger.kernel.org (open list:DOCUMENTATION) linux-kernel@vger.kernel.org (open list) bpf@vger.kernel.org (open list:BPF [MISC])
Does the extension exist on their minimum Sphinx version (1.7) or at least on the 2.24 in Documentation/requirements.txt?
Trying things out, looks like sphinx-prompt 1.5.0 will work with 2.4.4 as well.
I am just a sphinx newbie.. I can propose, but taking the job up of a massive Documentation cleanup across kernel documentation is a bit beyond my availability.
If you think this is the way forward, then I can propose to the kernel list.
Best regards
Heinrich
# # cdomain is badly broken in Sphinx 3+. Leaving it out generates *most* diff --git a/doc/sphinx/requirements.txt b/doc/sphinx/requirements.txt index 4f411f78d030..6ccbe527ee79 100644 --- a/doc/sphinx/requirements.txt +++ b/doc/sphinx/requirements.txt @@ -15,6 +15,7 @@ requests==2.31.0 six==1.16.0 snowballstemmer==2.2.0 Sphinx==3.4.3 +sphinx-prompt==1.5.0 sphinx-rtd-theme==1.0.0 sphinxcontrib-applehelp==1.0.2 sphinxcontrib-devhelp==1.0.2
On 8/24/23 17:40, Nishanth Menon wrote:
Sphinx-prompt[1] helps bring-in '.. prompt::' option that allows a better rendered documentation, yet be able to copy paste without picking up the prompt from rendered documentation.
[1] https://lore.kernel.org/all/87fs48rgto.fsf@baylibre.com/ Suggested-by: Mattijs Korpershoek mkorpershoek@baylibre.com Signed-off-by: Nishanth Menon nm@ti.com
Reviewed-by: Heinrich Schuchardt heinrich.schuchardt@canonical.com
On jeu., août 24, 2023 at 10:40, Nishanth Menon nm@ti.com wrote:
Sphinx-prompt[1] helps bring-in '.. prompt::' option that allows a better rendered documentation, yet be able to copy paste without picking up the prompt from rendered documentation.
[1] https://lore.kernel.org/all/87fs48rgto.fsf@baylibre.com/ Suggested-by: Mattijs Korpershoek mkorpershoek@baylibre.com Signed-off-by: Nishanth Menon nm@ti.com
Reviewed-by: Mattijs Korpershoek mkorpershoek@baylibre.com
Version picked is the best that works with Sphinx 3.4.3
doc/conf.py | 2 +- doc/sphinx/requirements.txt | 1 + 2 files changed, 2 insertions(+), 1 deletion(-)
diff --git a/doc/conf.py b/doc/conf.py index 00f241366477..5e2ff1c8f5e2 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -39,7 +39,7 @@ needs_sphinx = '2.4.4' extensions = ['kerneldoc', 'rstFlatTable', 'kernel_include', 'kfigure', 'sphinx.ext.ifconfig', # 'automarkup', 'maintainers_include', 'sphinx.ext.autosectionlabel',
'kernel_abi', 'kernel_feat']
'kernel_abi', 'kernel_feat', 'sphinx-prompt']# # cdomain is badly broken in Sphinx 3+. Leaving it out generates *most* diff --git a/doc/sphinx/requirements.txt b/doc/sphinx/requirements.txt index 4f411f78d030..6ccbe527ee79 100644 --- a/doc/sphinx/requirements.txt +++ b/doc/sphinx/requirements.txt @@ -15,6 +15,7 @@ requests==2.31.0 six==1.16.0 snowballstemmer==2.2.0 Sphinx==3.4.3 +sphinx-prompt==1.5.0 sphinx-rtd-theme==1.0.0 sphinxcontrib-applehelp==1.0.2 sphinxcontrib-devhelp==1.0.2 -- 2.40.0
Sphinx-prompt provides a handy scheme to provide documentation that renders nicely and yet provides a scheme to copy paste for users without having to hand-edit the copied text as is the result of code-block
[1] https://lore.kernel.org/all/87fs48rgto.fsf@baylibre.com/ Reported-by: Simon Glass sjg@chromium.org Suggested-by: Mattijs Korpershoek mkorpershoek@baylibre.com Signed-off-by: Nishanth Menon nm@ti.com --- doc/board/ti/k3.rst | 112 ++++++++++++++++++++++---------------------- 1 file changed, 57 insertions(+), 55 deletions(-)
diff --git a/doc/board/ti/k3.rst b/doc/board/ti/k3.rst index 1175b776ad48..ec447358ac39 100644 --- a/doc/board/ti/k3.rst +++ b/doc/board/ti/k3.rst @@ -194,13 +194,13 @@ All of that to say you will need both a 32bit and 64bit cross compiler .. k3_rst_include_end_common_env_vars_desc
.. k3_rst_include_start_common_env_vars_defn -.. code-block:: bash +.. prompt:: bash
- $ export CC32=arm-linux-gnueabihf- - $ export CC64=aarch64-linux-gnu- - $ export LNX_FW_PATH=path/to/ti-linux-firmware - $ export TFA_PATH=path/to/trusted-firmware-a - $ export OPTEE_PATH=path/to/optee_os + export CC32=arm-linux-gnueabihf- + export CC64=aarch64-linux-gnu- + export LNX_FW_PATH=path/to/ti-linux-firmware + export TFA_PATH=path/to/trusted-firmware-a + export OPTEE_PATH=path/to/optee_os .. k3_rst_include_end_common_env_vars_defn
We will also need some common environment variables set up for the various @@ -244,11 +244,11 @@ Building tiboot3.bin uses the split binary flow)
.. k3_rst_include_start_build_steps_spl_r5 -.. code-block:: bash +.. prompt:: bash
- $ # inside u-boot source - $ make $UBOOT_CFG_CORTEXR - $ make CROSS_COMPILE=$CC32 BINMAN_INDIRS=$LNX_FW_PATH + # inside u-boot source + make $UBOOT_CFG_CORTEXR + make CROSS_COMPILE=$CC32 BINMAN_INDIRS=$LNX_FW_PATH .. k3_rst_include_end_build_steps_spl_r5
At this point you should have all the needed binaries to boot the wakeup @@ -280,11 +280,11 @@ firmware if your device using a split firmware. application cores on the main domain.
.. k3_rst_include_start_build_steps_tfa -.. code-block:: bash +.. prompt:: bash
- $ # inside trusted-firmware-a source - $ make CROSS_COMPILE=$CC64 ARCH=aarch64 PLAT=k3 SPD=opteed $TFA_EXTRA_ARGS \ - TARGET_BOARD=$TFA_BOARD + # inside trusted-firmware-a source + make CROSS_COMPILE=$CC64 ARCH=aarch64 PLAT=k3 SPD=opteed $TFA_EXTRA_ARGS \ + TARGET_BOARD=$TFA_BOARD .. k3_rst_include_end_build_steps_tfa
Typically all `j7*` devices will use `TARGET_BOARD=generic` or `TARGET_BOARD @@ -296,11 +296,11 @@ use the `lite` option. using the TrustZone technology built into the core.
.. k3_rst_include_start_build_steps_optee -.. code-block:: bash +.. prompt:: bash
- $ # inside optee_os source - $ make CROSS_COMPILE=$CC32 CROSS_COMPILE64=$CC64 CFG_ARM64_core=y $OPTEE_EXTRA_ARGS \ - PLATFORM=$OPTEE_PLATFORM + # inside optee_os source + make CROSS_COMPILE=$CC32 CROSS_COMPILE64=$CC64 CFG_ARM64_core=y $OPTEE_EXTRA_ARGS \ + PLATFORM=$OPTEE_PLATFORM .. k3_rst_include_end_build_steps_optee
4. Finally, after TF-A has initialized the main domain and OP-TEE has @@ -308,11 +308,11 @@ use the `lite` option. 64bit core in the main domain.
.. k3_rst_include_start_build_steps_uboot -.. code-block:: bash +.. prompt:: bash
- $ # inside u-boot source - $ make $UBOOT_CFG_CORTEXA - $ make CROSS_COMPILE=$CC64 BINMAN_INDIRS=$LNX_FW_PATH \ + # inside u-boot source + make $UBOOT_CFG_CORTEXA + make CROSS_COMPILE=$CC64 BINMAN_INDIRS=$LNX_FW_PATH \ BL31=$TFA_PATH/build/k3/$TFA_BOARD/release/bl31.bin \ TEE=$OPTEE_PATH/out/arm-plat-k3/core/tee-raw.bin .. k3_rst_include_end_build_steps_uboot @@ -407,14 +407,14 @@ and the same can be extended to other platforms be passing to mkimage for signing the fitImage and embedding the key in the u-boot dtb.
- .. code-block:: bash + .. prompt:: bash
mkimage -r -f fitImage.its -k $UBOOT_PATH/board/ti/keys -K $UBOOT_PATH/build/a72/dts/dt.dtb
For signing a secondary platform, pass the -K parameter to that DTB
- .. code-block:: bash + .. prompt:: bash
mkimage -f fitImage.its -k $UBOOT_PATH/board/ti/keys -K $UBOOT_PATH/build/a72/arch/arm/dts/k3-j721e-sk.dtb @@ -473,10 +473,11 @@ then the saveenv command and can be used across various bootmodes too.
**Writing to MMC/EMMC**
-.. code-block:: +.. prompt:: bash + :prompts: =>
- => env export -t $loadaddr <list of variables> - => fatwrite mmc ${mmcdev} ${loadaddr} ${bootenvfile} ${filesize} + env export -t $loadaddr <list of variables> + fatwrite mmc ${mmcdev} ${loadaddr} ${bootenvfile} ${filesize}
**Reading from MMC/EMMC**
@@ -486,10 +487,11 @@ mmcdev) and set the environments. If manually needs to be done then the environment can be read from the filesystem and then imported
-.. code-block:: +.. prompt:: bash + :prompts: =>
- => fatload mmc ${mmcdev} ${loadaddr} ${bootenvfile} - => env import -t ${loadaddr} ${filesize} + fatload mmc ${mmcdev} ${loadaddr} ${bootenvfile} + env import -t ${loadaddr} ${filesize}
.. _k3_rst_refer_openocd:
@@ -546,7 +548,7 @@ Refer to the release notes corresponding to the `OpenOCD version box support by OpenOCD. The board-specific documentation will cover the details and any adapter/dongle recommendations.
-.. code-block:: bash +.. prompt:: bash
openocd -v
@@ -564,21 +566,21 @@ systems, but equivalent instructions should exist for systems with other package managers. Please refer to the `OpenOCD Documentation https://openocd.org/`_ for more recent installation steps.
-.. code-block:: bash +.. prompt:: bash
- $ # Check the packages to be installed: needs deb-src in sources.list - $ sudo apt build-dep openocd - $ # The following list is NOT complete - please check the latest - $ sudo apt-get install libtool pkg-config texinfo libusb-dev \ + # Check the packages to be installed: needs deb-src in sources.list + sudo apt build-dep openocd + # The following list is NOT complete - please check the latest + sudo apt-get install libtool pkg-config texinfo libusb-dev \ libusb-1.0.0-dev libftdi-dev libhidapi-dev autoconf automake - $ git clone https://github.com/openocd-org/openocd.git openocd - $ cd openocd - $ git submodule init - $ git submodule update - $ ./bootstrap - $ ./configure --prefix=/usr/local/ - $ make -j`nproc` - $ sudo make install + git clone https://github.com/openocd-org/openocd.git openocd + cd openocd + git submodule init + git submodule update + ./bootstrap + ./configure --prefix=/usr/local/ + make -j`nproc` + sudo make install
.. note::
@@ -594,28 +596,28 @@ The step is not necessary if the distribution supports the OpenOCD, but if building from a source, ensure that the udev rules are installed correctly to ensure a sane system.
-.. code-block:: bash +.. prompt:: bash
# Go to the OpenOCD source directory - $ cd openocd - # Copy the udev rules to the correct system location - $ sudo cp ./contrib/60-openocd.rules \ + cd openocd + Copy the udev rules to the correct system location + sudo cp ./contrib/60-openocd.rules \ ./src/jtag/drivers/libjaylink/contrib/99-libjaylink.rules \ /etc/udev/rules.d/ # Get Udev to load the new rules up - $ sudo udevadm control --reload-rules + sudo udevadm control --reload-rules # Use the new rules on existing connected devices - $ sudo udevadm trigger + sudo udevadm trigger
Step 2: Setup GDB ^^^^^^^^^^^^^^^^^
Most systems come with gdb-multiarch package.
-.. code-block:: bash +.. prompt:: bash
# Install gdb-multiarch package - $ sudo apt-get install gdb-multiarch + sudo apt-get install gdb-multiarch
Though using GDB natively is normal, developers with interest in using IDE may find a few of these interesting: @@ -828,7 +830,7 @@ Startup OpenOCD to debug the platform as follows:
.. k3_rst_include_start_openocd_cfg_XDS110
-.. code-block:: bash +.. prompt:: bash
openocd -f board/{board_of_choice}.cfg
@@ -842,7 +844,7 @@ Startup OpenOCD to debug the platform as follows: https://github.com/openocd-org/openocd/blob/master/tcl/target/ti_k3.cfg#L59`_ to decide if the SoC is supported or not.
-.. code-block:: bash +.. prompt:: bash
openocd -f openocd_connect.cfg
@@ -917,7 +919,7 @@ To debug using this server, use GDB directly or your preferred GDB-based IDE. To start up GDB in the terminal, run the following command.
-.. code-block:: bash +.. prompt:: bash
gdb-multiarch
On 24.08.23 17:40, Nishanth Menon wrote:
Sphinx-prompt provides a handy scheme to provide documentation that renders nicely and yet provides a scheme to copy paste for users without having to hand-edit the copied text as is the result of code-block
[1] https://lore.kernel.org/all/87fs48rgto.fsf@baylibre.com/ Reported-by: Simon Glass sjg@chromium.org Suggested-by: Mattijs Korpershoek mkorpershoek@baylibre.com Signed-off-by: Nishanth Menon nm@ti.com
doc/board/ti/k3.rst | 112 ++++++++++++++++++++++---------------------- 1 file changed, 57 insertions(+), 55 deletions(-)
diff --git a/doc/board/ti/k3.rst b/doc/board/ti/k3.rst index 1175b776ad48..ec447358ac39 100644 --- a/doc/board/ti/k3.rst +++ b/doc/board/ti/k3.rst @@ -194,13 +194,13 @@ All of that to say you will need both a 32bit and 64bit cross compiler .. k3_rst_include_end_common_env_vars_desc
.. k3_rst_include_start_common_env_vars_defn -.. code-block:: bash +.. prompt:: bash
- $ export CC32=arm-linux-gnueabihf-
- $ export CC64=aarch64-linux-gnu-
- $ export LNX_FW_PATH=path/to/ti-linux-firmware
- $ export TFA_PATH=path/to/trusted-firmware-a
- $ export OPTEE_PATH=path/to/optee_os
export CC32=arm-linux-gnueabihf-
export CC64=aarch64-linux-gnu-
export LNX_FW_PATH=path/to/ti-linux-firmware
export TFA_PATH=path/to/trusted-firmware-a
export OPTEE_PATH=path/to/optee_os .. k3_rst_include_end_common_env_vars_defn
We will also need some common environment variables set up for the various
@@ -244,11 +244,11 @@ Building tiboot3.bin uses the split binary flow)
.. k3_rst_include_start_build_steps_spl_r5 -.. code-block:: bash +.. prompt:: bash
- $ # inside u-boot source
- $ make $UBOOT_CFG_CORTEXR
- $ make CROSS_COMPILE=$CC32 BINMAN_INDIRS=$LNX_FW_PATH
# inside u-boot source
make $UBOOT_CFG_CORTEXR
make CROSS_COMPILE=$CC32 BINMAN_INDIRS=$LNX_FW_PATH .. k3_rst_include_end_build_steps_spl_r5
At this point you should have all the needed binaries to boot the wakeup
@@ -280,11 +280,11 @@ firmware if your device using a split firmware. application cores on the main domain.
.. k3_rst_include_start_build_steps_tfa -.. code-block:: bash +.. prompt:: bash
- $ # inside trusted-firmware-a source
- $ make CROSS_COMPILE=$CC64 ARCH=aarch64 PLAT=k3 SPD=opteed $TFA_EXTRA_ARGS \
TARGET_BOARD=$TFA_BOARD
# inside trusted-firmware-a source
make CROSS_COMPILE=$CC64 ARCH=aarch64 PLAT=k3 SPD=opteed $TFA_EXTRA_ARGS \
TARGET_BOARD=$TFA_BOARD.. k3_rst_include_end_build_steps_tfa
Typically all `j7*` devices will use `TARGET_BOARD=generic` or `TARGET_BOARD
@@ -296,11 +296,11 @@ use the `lite` option. using the TrustZone technology built into the core.
.. k3_rst_include_start_build_steps_optee -.. code-block:: bash +.. prompt:: bash
- $ # inside optee_os source
- $ make CROSS_COMPILE=$CC32 CROSS_COMPILE64=$CC64 CFG_ARM64_core=y $OPTEE_EXTRA_ARGS \
PLATFORM=$OPTEE_PLATFORM
# inside optee_os source
make CROSS_COMPILE=$CC32 CROSS_COMPILE64=$CC64 CFG_ARM64_core=y $OPTEE_EXTRA_ARGS \
PLATFORM=$OPTEE_PLATFORM.. k3_rst_include_end_build_steps_optee
- Finally, after TF-A has initialized the main domain and OP-TEE has
@@ -308,11 +308,11 @@ use the `lite` option. 64bit core in the main domain.
.. k3_rst_include_start_build_steps_uboot -.. code-block:: bash +.. prompt:: bash
- $ # inside u-boot source
- $ make $UBOOT_CFG_CORTEXA
- $ make CROSS_COMPILE=$CC64 BINMAN_INDIRS=$LNX_FW_PATH \
- # inside u-boot source
- make $UBOOT_CFG_CORTEXA
- make CROSS_COMPILE=$CC64 BINMAN_INDIRS=$LNX_FW_PATH \ BL31=$TFA_PATH/build/k3/$TFA_BOARD/release/bl31.bin \ TEE=$OPTEE_PATH/out/arm-plat-k3/core/tee-raw.bin .. k3_rst_include_end_build_steps_uboot
@@ -407,14 +407,14 @@ and the same can be extended to other platforms be passing to mkimage for signing the fitImage and embedding the key in the u-boot dtb.
- .. code-block:: bash
.. prompt:: bash
mkimage -r -f fitImage.its -k $UBOOT_PATH/board/ti/keys -K $UBOOT_PATH/build/a72/dts/dt.dtb
For signing a secondary platform, pass the -K parameter to that DTB
- .. code-block:: bash
.. prompt:: bash
mkimage -f fitImage.its -k $UBOOT_PATH/board/ti/keys -K $UBOOT_PATH/build/a72/arch/arm/dts/k3-j721e-sk.dtb
@@ -473,10 +473,11 @@ then the saveenv command and can be used across various bootmodes too.
**Writing to MMC/EMMC**
-.. code-block:: +.. prompt:: bash
- :prompts: =>
- => env export -t $loadaddr <list of variables>
- => fatwrite mmc ${mmcdev} ${loadaddr} ${bootenvfile} ${filesize}
env export -t $loadaddr <list of variables>
fatwrite mmc ${mmcdev} ${loadaddr} ${bootenvfile} ${filesize}
**Reading from MMC/EMMC**
@@ -486,10 +487,11 @@ mmcdev) and set the environments. If manually needs to be done then the environment can be read from the filesystem and then imported
-.. code-block:: +.. prompt:: bash
- :prompts: =>
- => fatload mmc ${mmcdev} ${loadaddr} ${bootenvfile}
- => env import -t ${loadaddr} ${filesize}
fatload mmc ${mmcdev} ${loadaddr} ${bootenvfile}
env import -t ${loadaddr} ${filesize}
.. _k3_rst_refer_openocd:
@@ -546,7 +548,7 @@ Refer to the release notes corresponding to the `OpenOCD version box support by OpenOCD. The board-specific documentation will cover the details and any adapter/dongle recommendations.
-.. code-block:: bash +.. prompt:: bash
openocd -v
@@ -564,21 +566,21 @@ systems, but equivalent instructions should exist for systems with other package managers. Please refer to the `OpenOCD Documentation https://openocd.org/`_ for more recent installation steps.
-.. code-block:: bash +.. prompt:: bash
- $ # Check the packages to be installed: needs deb-src in sources.list
- $ sudo apt build-dep openocd
- $ # The following list is NOT complete - please check the latest
- $ sudo apt-get install libtool pkg-config texinfo libusb-dev \
- # Check the packages to be installed: needs deb-src in sources.list
- sudo apt build-dep openocd
- # The following list is NOT complete - please check the latest
- sudo apt-get install libtool pkg-config texinfo libusb-dev \ libusb-1.0.0-dev libftdi-dev libhidapi-dev autoconf automake
- $ git clone https://github.com/openocd-org/openocd.git openocd
- $ cd openocd
- $ git submodule init
- $ git submodule update
- $ ./bootstrap
- $ ./configure --prefix=/usr/local/
- $ make -j`nproc`
- $ sudo make install
git clone https://github.com/openocd-org/openocd.git openocd
cd openocd
git submodule init
git submodule update
./bootstrap
./configure --prefix=/usr/local/
make -j`nproc`
sudo make install
.. note::
@@ -594,28 +596,28 @@ The step is not necessary if the distribution supports the OpenOCD, but if building from a source, ensure that the udev rules are installed correctly to ensure a sane system.
-.. code-block:: bash +.. prompt:: bash
# Go to the OpenOCD source directory
- $ cd openocd
- # Copy the udev rules to the correct system location
- $ sudo cp ./contrib/60-openocd.rules \
- cd openocd
- Copy the udev rules to the correct system location
- sudo cp ./contrib/60-openocd.rules \ ./src/jtag/drivers/libjaylink/contrib/99-libjaylink.rules \ /etc/udev/rules.d/ # Get Udev to load the new rules up
- $ sudo udevadm control --reload-rules
- sudo udevadm control --reload-rules # Use the new rules on existing connected devices
- $ sudo udevadm trigger
sudo udevadm trigger
Step 2: Setup GDB ^^^^^^^^^^^^^^^^^
Most systems come with gdb-multiarch package.
-.. code-block:: bash +.. prompt:: bash
.. prompt:: bash $ will enforce $ as prompt?
Cf. http://sbrunner.github.io/sphinx-prompt/
Best regards
Heinrich
# Install gdb-multiarch package
- $ sudo apt-get install gdb-multiarch
sudo apt-get install gdb-multiarch
Though using GDB natively is normal, developers with interest in using IDE may find a few of these interesting:
@@ -828,7 +830,7 @@ Startup OpenOCD to debug the platform as follows:
.. k3_rst_include_start_openocd_cfg_XDS110
-.. code-block:: bash +.. prompt:: bash
openocd -f board/{board_of_choice}.cfg@@ -842,7 +844,7 @@ Startup OpenOCD to debug the platform as follows: https://github.com/openocd-org/openocd/blob/master/tcl/target/ti_k3.cfg#L59`_ to decide if the SoC is supported or not.
-.. code-block:: bash +.. prompt:: bash
openocd -f openocd_connect.cfg@@ -917,7 +919,7 @@ To debug using this server, use GDB directly or your preferred GDB-based IDE. To start up GDB in the terminal, run the following command.
-.. code-block:: bash +.. prompt:: bash
gdb-multiarch
On 17:50-20230824, Heinrich Schuchardt wrote: [...]
.. prompt:: bash $ will enforce $ as prompt?
Yes, that works great.
On 8/24/23 17:40, Nishanth Menon wrote:
Sphinx-prompt provides a handy scheme to provide documentation that renders nicely and yet provides a scheme to copy paste for users without having to hand-edit the copied text as is the result of code-block
[1] https://lore.kernel.org/all/87fs48rgto.fsf@baylibre.com/ Reported-by: Simon Glass sjg@chromium.org Suggested-by: Mattijs Korpershoek mkorpershoek@baylibre.com Signed-off-by: Nishanth Menon nm@ti.com
Reviewed-by: Heinrich Schuchardt heinrich.schuchardt@canonical.com
On jeu., août 24, 2023 at 10:40, Nishanth Menon nm@ti.com wrote:
Sphinx-prompt provides a handy scheme to provide documentation that renders nicely and yet provides a scheme to copy paste for users without having to hand-edit the copied text as is the result of code-block
[1] https://lore.kernel.org/all/87fs48rgto.fsf@baylibre.com/ Reported-by: Simon Glass sjg@chromium.org Suggested-by: Mattijs Korpershoek mkorpershoek@baylibre.com Signed-off-by: Nishanth Menon nm@ti.com
Reviewed-by: Mattijs Korpershoek mkorpershoek@baylibre.com
Small nitpick below, which is probably a matter of preference
doc/board/ti/k3.rst | 112 ++++++++++++++++++++++---------------------- 1 file changed, 57 insertions(+), 55 deletions(-)
diff --git a/doc/board/ti/k3.rst b/doc/board/ti/k3.rst index 1175b776ad48..ec447358ac39 100644 --- a/doc/board/ti/k3.rst +++ b/doc/board/ti/k3.rst @@ -194,13 +194,13 @@ All of that to say you will need both a 32bit and 64bit cross compiler .. k3_rst_include_end_common_env_vars_desc
.. k3_rst_include_start_common_env_vars_defn -.. code-block:: bash +.. prompt:: bash
- $ export CC32=arm-linux-gnueabihf-
- $ export CC64=aarch64-linux-gnu-
- $ export LNX_FW_PATH=path/to/ti-linux-firmware
- $ export TFA_PATH=path/to/trusted-firmware-a
- $ export OPTEE_PATH=path/to/optee_os
- export CC32=arm-linux-gnueabihf-
- export CC64=aarch64-linux-gnu-
- export LNX_FW_PATH=path/to/ti-linux-firmware
- export TFA_PATH=path/to/trusted-firmware-a
- export OPTEE_PATH=path/to/optee_os
.. k3_rst_include_end_common_env_vars_defn
We will also need some common environment variables set up for the various @@ -244,11 +244,11 @@ Building tiboot3.bin uses the split binary flow)
.. k3_rst_include_start_build_steps_spl_r5 -.. code-block:: bash +.. prompt:: bash
- $ # inside u-boot source
- $ make $UBOOT_CFG_CORTEXR
- $ make CROSS_COMPILE=$CC32 BINMAN_INDIRS=$LNX_FW_PATH
- # inside u-boot source
- make $UBOOT_CFG_CORTEXR
- make CROSS_COMPILE=$CC32 BINMAN_INDIRS=$LNX_FW_PATH
.. k3_rst_include_end_build_steps_spl_r5
At this point you should have all the needed binaries to boot the wakeup @@ -280,11 +280,11 @@ firmware if your device using a split firmware. application cores on the main domain.
.. k3_rst_include_start_build_steps_tfa -.. code-block:: bash +.. prompt:: bash
- $ # inside trusted-firmware-a source
- $ make CROSS_COMPILE=$CC64 ARCH=aarch64 PLAT=k3 SPD=opteed $TFA_EXTRA_ARGS \
TARGET_BOARD=$TFA_BOARD
- # inside trusted-firmware-a source
- make CROSS_COMPILE=$CC64 ARCH=aarch64 PLAT=k3 SPD=opteed $TFA_EXTRA_ARGS \
TARGET_BOARD=$TFA_BOARD.. k3_rst_include_end_build_steps_tfa
Typically all `j7*` devices will use `TARGET_BOARD=generic` or `TARGET_BOARD @@ -296,11 +296,11 @@ use the `lite` option. using the TrustZone technology built into the core.
.. k3_rst_include_start_build_steps_optee -.. code-block:: bash +.. prompt:: bash
- $ # inside optee_os source
- $ make CROSS_COMPILE=$CC32 CROSS_COMPILE64=$CC64 CFG_ARM64_core=y $OPTEE_EXTRA_ARGS \
PLATFORM=$OPTEE_PLATFORM
- # inside optee_os source
- make CROSS_COMPILE=$CC32 CROSS_COMPILE64=$CC64 CFG_ARM64_core=y $OPTEE_EXTRA_ARGS \
PLATFORM=$OPTEE_PLATFORM.. k3_rst_include_end_build_steps_optee
- Finally, after TF-A has initialized the main domain and OP-TEE has
@@ -308,11 +308,11 @@ use the `lite` option. 64bit core in the main domain.
.. k3_rst_include_start_build_steps_uboot -.. code-block:: bash +.. prompt:: bash
- $ # inside u-boot source
- $ make $UBOOT_CFG_CORTEXA
- $ make CROSS_COMPILE=$CC64 BINMAN_INDIRS=$LNX_FW_PATH \
- # inside u-boot source
- make $UBOOT_CFG_CORTEXA
- make CROSS_COMPILE=$CC64 BINMAN_INDIRS=$LNX_FW_PATH \ BL31=$TFA_PATH/build/k3/$TFA_BOARD/release/bl31.bin \ TEE=$OPTEE_PATH/out/arm-plat-k3/core/tee-raw.bin
.. k3_rst_include_end_build_steps_uboot @@ -407,14 +407,14 @@ and the same can be extended to other platforms be passing to mkimage for signing the fitImage and embedding the key in the u-boot dtb.
- .. code-block:: bash
.. prompt:: bash
mkimage -r -f fitImage.its -k $UBOOT_PATH/board/ti/keys -K $UBOOT_PATH/build/a72/dts/dt.dtb
For signing a secondary platform, pass the -K parameter to that DTB
- .. code-block:: bash
.. prompt:: bash
mkimage -f fitImage.its -k $UBOOT_PATH/board/ti/keys -K $UBOOT_PATH/build/a72/arch/arm/dts/k3-j721e-sk.dtb
@@ -473,10 +473,11 @@ then the saveenv command and can be used across various bootmodes too.
**Writing to MMC/EMMC**
-.. code-block:: +.. prompt:: bash
- :prompts: =>
nitpick: This can be a one-liner by using the "prompts" positional argument
.. prompt:: bash =>
- => env export -t $loadaddr <list of variables>
- => fatwrite mmc ${mmcdev} ${loadaddr} ${bootenvfile} ${filesize}
- env export -t $loadaddr <list of variables>
- fatwrite mmc ${mmcdev} ${loadaddr} ${bootenvfile} ${filesize}
**Reading from MMC/EMMC**
@@ -486,10 +487,11 @@ mmcdev) and set the environments. If manually needs to be done then the environment can be read from the filesystem and then imported
-.. code-block:: +.. prompt:: bash
- :prompts: =>
nitpick: Same here
- => fatload mmc ${mmcdev} ${loadaddr} ${bootenvfile}
- => env import -t ${loadaddr} ${filesize}
- fatload mmc ${mmcdev} ${loadaddr} ${bootenvfile}
- env import -t ${loadaddr} ${filesize}
.. _k3_rst_refer_openocd:
@@ -546,7 +548,7 @@ Refer to the release notes corresponding to the `OpenOCD version box support by OpenOCD. The board-specific documentation will cover the details and any adapter/dongle recommendations.
-.. code-block:: bash +.. prompt:: bash
openocd -v
@@ -564,21 +566,21 @@ systems, but equivalent instructions should exist for systems with other package managers. Please refer to the `OpenOCD Documentation https://openocd.org/`_ for more recent installation steps.
-.. code-block:: bash +.. prompt:: bash
- $ # Check the packages to be installed: needs deb-src in sources.list
- $ sudo apt build-dep openocd
- $ # The following list is NOT complete - please check the latest
- $ sudo apt-get install libtool pkg-config texinfo libusb-dev \
- # Check the packages to be installed: needs deb-src in sources.list
- sudo apt build-dep openocd
- # The following list is NOT complete - please check the latest
- sudo apt-get install libtool pkg-config texinfo libusb-dev \ libusb-1.0.0-dev libftdi-dev libhidapi-dev autoconf automake
- $ git clone https://github.com/openocd-org/openocd.git openocd
- $ cd openocd
- $ git submodule init
- $ git submodule update
- $ ./bootstrap
- $ ./configure --prefix=/usr/local/
- $ make -j`nproc`
- $ sudo make install
- git clone https://github.com/openocd-org/openocd.git openocd
- cd openocd
- git submodule init
- git submodule update
- ./bootstrap
- ./configure --prefix=/usr/local/
- make -j`nproc`
- sudo make install
.. note::
@@ -594,28 +596,28 @@ The step is not necessary if the distribution supports the OpenOCD, but if building from a source, ensure that the udev rules are installed correctly to ensure a sane system.
-.. code-block:: bash +.. prompt:: bash
# Go to the OpenOCD source directory
- $ cd openocd
- # Copy the udev rules to the correct system location
- $ sudo cp ./contrib/60-openocd.rules \
- cd openocd
- Copy the udev rules to the correct system location
- sudo cp ./contrib/60-openocd.rules \ ./src/jtag/drivers/libjaylink/contrib/99-libjaylink.rules \ /etc/udev/rules.d/ # Get Udev to load the new rules up
- $ sudo udevadm control --reload-rules
- sudo udevadm control --reload-rules # Use the new rules on existing connected devices
- $ sudo udevadm trigger
- sudo udevadm trigger
Step 2: Setup GDB ^^^^^^^^^^^^^^^^^
Most systems come with gdb-multiarch package.
-.. code-block:: bash +.. prompt:: bash
# Install gdb-multiarch package
- $ sudo apt-get install gdb-multiarch
- sudo apt-get install gdb-multiarch
Though using GDB natively is normal, developers with interest in using IDE may find a few of these interesting: @@ -828,7 +830,7 @@ Startup OpenOCD to debug the platform as follows:
.. k3_rst_include_start_openocd_cfg_XDS110
-.. code-block:: bash +.. prompt:: bash
openocd -f board/{board_of_choice}.cfg
@@ -842,7 +844,7 @@ Startup OpenOCD to debug the platform as follows: https://github.com/openocd-org/openocd/blob/master/tcl/target/ti_k3.cfg#L59`_ to decide if the SoC is supported or not.
-.. code-block:: bash +.. prompt:: bash
openocd -f openocd_connect.cfg
@@ -917,7 +919,7 @@ To debug using this server, use GDB directly or your preferred GDB-based IDE. To start up GDB in the terminal, run the following command.
-.. code-block:: bash +.. prompt:: bash
gdb-multiarch
-- 2.40.0
On 10:07-20230828, Mattijs Korpershoek wrote: [...]
-.. code-block:: +.. prompt:: bash
- :prompts: =>
nitpick: This can be a one-liner by using the "prompts" positional argument
.. prompt:: bash =>
- => env export -t $loadaddr <list of variables>
- => fatwrite mmc ${mmcdev} ${loadaddr} ${bootenvfile} ${filesize}
- env export -t $loadaddr <list of variables>
- fatwrite mmc ${mmcdev} ${loadaddr} ${bootenvfile} ${filesize}
**Reading from MMC/EMMC**
@@ -486,10 +487,11 @@ mmcdev) and set the environments. If manually needs to be done then the environment can be read from the filesystem and then imported
-.. code-block:: +.. prompt:: bash
- :prompts: =>
nitpick: Same here
Thanks for catching, will fixup in a follow on series.
participants (3)
-
Heinrich Schuchardt -
Mattijs Korpershoek -
Nishanth Menon