diff --git a/samples/subsys/shell/devmem_load/README.md b/samples/subsys/shell/devmem_load/README.md deleted file mode 100644 index 13ef263443d3b..0000000000000 --- a/samples/subsys/shell/devmem_load/README.md +++ /dev/null @@ -1,52 +0,0 @@ -# Zephyr devmem load command -This module add a `devmem load` command that allows data to be loaded into device memory. -The `devmem load` command is supported by every transport the shell can run on. - -After using a command in the Zephyr shell, the device reads all transferred data and writes to an address in the memory. -The transfer ends when the user presses `ctrl-x + ctrl-q`. - -## Usage -Note: when using the devmem load command over UART it is recommended to use interrupts whenever possible. -If this is not possible, reduce the baud rate to 9600. - -If you use poll you should also use `prj_poll.conf` instead of `prj.conf`. -## Building - -The sample can be built for several platforms, the following commands build and run the application with a shell for the FRDM-K64F board. -```bash -west build -b frdm_k64f samples/subsys/shell/devmem_load -west flash -``` - -Building for boards without UART interrupt support: -```bash -west build -b native_sim -- -DCONF_FILE=prj_poll.conf samples/subsys/shell/devmem_load -``` -## Running -After connecting to the UART console you should see the following output: -```bash -uart:~$ -``` -The `devmem load` command can now be used (`devmem load [option] [address]`): -```bash -uart:~$ devmem load 0x20020000 -Loading... -press ctrl-x ctrl-q to escape -``` - -Now, the `devmem load` is waiting for data. -You can either type it directly from the console or send it from the host PC (replace `ttyX` with the appropriate one for your UART console): -```bash -xxd -p data > /dev/ttyX -``` -(It is important to use plain-style hex dump) -Once the data is transferred, use `ctrl-x + ctrl-q` to quit the loader. -It will print the number of the bytes read and return to the shell: -```bash -Number of bytes read: 3442 -uart:~$ -``` - -## Options -Currently, the `devmem load` command supports the following argument: -* `-e` little endian parse e.g. `0xDEADBEFF -> 0xFFBEADDE` diff --git a/samples/subsys/shell/devmem_load/README.rst b/samples/subsys/shell/devmem_load/README.rst new file mode 100644 index 0000000000000..58d3f9766f092 --- /dev/null +++ b/samples/subsys/shell/devmem_load/README.rst @@ -0,0 +1,118 @@ +.. zephyr:code-sample:: shell-devmem-load + :name: devmem load shell + :relevant-api: shell_api + + Load data to device memory using devmem shell cmd. + +Overview +******** + +This module adds a ``devmem load`` command that allows data to be loaded into +device memory. The ``devmem load`` command is supported by every transport the +Zephyr shell can run on. + +After invoking the command in the Zephyr shell, the device receives the +transferred data and writes it to the specified memory address. +The transfer ends when the user presses :kbd:`Ctrl+X` followed by :kbd:`Ctrl+Q`. + +Requirements +************ + +* A target configured with the shell interface, exposed through any of + its :ref:`backends `. + +Building and Running +******************** + +The sample can be built for several platforms. + +Emulation Targets +================= + +The sample may run on emulation targets. The following commands build the +application for the qemu_x86. + +.. zephyr-app-commands:: + :zephyr-app: samples/subsys/shell/devmem_load + :host-os: unix + :board: qemu_x86 + :goals: run + :compact: + +After running the application, the console displays the shell interface, and +shows the shell prompt, at which point the user may type in the ``devmem load`` command. + +.. note:: + + When using the ``devmem load`` command over UART, it is recommended to use + interrupts whenever possible. + If this is not possible, reduce the baud rate to 9600. + + If you use polling mode, you should also use ``prj_poll.conf`` instead of + ``prj.conf``. + +Building for boards without UART interrupt support: + +.. zephyr-app-commands:: + :zephyr-app: samples/subsys/shell/devmem_load + :host-os: unix + :board: native_sim + :gen-args: -DCONF_FILE=prj_poll.conf + :goals: run + :compact: + +On-Hardware +=========== + +.. zephyr-app-commands:: + :zephyr-app: samples/subsys/shell/shell_module + :host-os: unix + :board: nrf52840dk/nrf52840 + :goals: flash + :compact: + +Sample Output +************* + +After connecting to the UART console, you should see the following output: + +.. code-block:: console + + uart:~$ + +The ``devmem load`` command can now be used: + +.. code-block:: console + + uart:~$ devmem load 0x20020000 + Loading... + press ctrl-x ctrl-q to escape + +At this point, the ``devmem load`` command waits for data input. +You can either type the data directly from the console or send it from the host PC +(replace ``ttyX`` with your UART console device): + +.. code-block:: bash + + xxd -p data > /dev/ttyX + +.. note:: + + It is important to use a plain-style hex dump. + +Once the data transfer is complete, use :kbd:`Ctrl+X` followed by :kbd:`Ctrl+Q` +to quit the loader. The shell then displays the number of bytes read and returns +to the prompt: + +.. code-block:: console + + Number of bytes read: 3442 + uart:~$ + +Options +======== + +The ``devmem load`` command currently supports the following option: + +* ``-e`` + Interpret data as little endian, e.g. ``0xDEADBEFF`` → ``0xFFBEADDE``.