summaryrefslogtreecommitdiffstats
path: root/shell
diff options
context:
space:
mode:
authorChris Johns <chrisj@rtems.org>2016-01-23 10:14:53 +1100
committerAmar Takhar <verm@darkbeer.org>2016-05-02 20:51:25 -0400
commitfabe6d020fef5bdefe8519c8a1b36c8ef68c6e97 (patch)
tree3f9fc95027116bb567666bb85c71f7ddf1599fab /shell
parentdf773360c902958c0b1b62512dcccd483020f645 (diff)
downloadrtems-docs-fabe6d020fef5bdefe8519c8a1b36c8ef68c6e97.tar.bz2
Clean up the memory commands.
Diffstat (limited to 'shell')
-rw-r--r--shell/memory_commands.rst348
1 files changed, 186 insertions, 162 deletions
diff --git a/shell/memory_commands.rst b/shell/memory_commands.rst
index 0c80574..8a2aa72 100644
--- a/shell/memory_commands.rst
+++ b/shell/memory_commands.rst
@@ -1,3 +1,7 @@
+.. COMMENT: COPYRIGHT (c) 1988-2008.
+.. COMMENT: On-Line Applications Research Corporation (OAR).
+.. COMMENT: All rights reserved.
+
Memory Commands
###############
@@ -6,19 +10,19 @@ Introduction
The RTEMS shell has the following memory commands:
-- ``mdump`` - Display contents of memory
+- mdump_ - Display contents of memory
-- ``wdump`` - Display contents of memory (word)
+- wdump_ - Display contents of memory (word)
-- ``ldump`` - Display contents of memory (longword)
+- ldump_ - Display contents of memory (longword)
-- ``medit`` - Modify contents of memory
+- medit_ - Modify contents of memory
-- ``mfill`` - File memory with pattern
+- mfill_ - File memory with pattern
-- ``mmove`` - Move contents of memory
+- mmove_ - Move contents of memory
-- ``malloc`` - Obtain information on C Program Heap
+- malloc_ - Obtain information on C Program Heap
Commands
========
@@ -28,27 +32,29 @@ subsection is dedicated to each of the commands and
describes the behavior and configuration of that
command as well as providing an example usage.
+.. _mdump:
+
mdump - display contents of memory
----------------------------------
.. index:: mdump
**SYNOPSYS:**
-.. code:: c
+.. code:: shell
- mdump \[address \[length \[size]]]
+ mdump [address [length [size]]]
**DESCRIPTION:**
-This command displays the contents of memory at the ``address``
-and ``length`` in ``size`` byte units specified on the command line.
+This command displays the contents of memory at the ``address`` and ``length``
+in ``size`` byte units specified on the command line.
-When ``size`` is not provided, it defaults to ``1`` byte units.
-Values of ``1``, ``2``, and ``4`` are valid; all others will
-cause an error to be reported.
+When ``size`` is not provided, it defaults to ``1`` byte units. Values of
+``1``, ``2``, and ``4`` are valid; all others will cause an error to be
+reported.
-When ``length`` is not provided, it defaults to ``320`` which
-is twenty lines of output with sixteen bytes of output per line.
+When ``length`` is not provided, it defaults to ``320`` which is twenty lines
+of output with sixteen bytes of output per line.
When ``address`` is not provided, it defaults to ``0x00000000``.
@@ -64,15 +70,16 @@ program fault.
**EXAMPLES:**
The following is an example of how to use ``mdump``:
-.. code:: c
- SHLL \[/] $ mdump 0x10000 32
+.. code:: shell
+
+ SHLL [/] $ mdump 0x10000 32
0x0001000000 00 00 00 00 00 00 00-00 00 00 00 00 00 00 00 ................
0x0001001000 00 00 00 00 00 00 00-00 00 00 00 00 00 00 00 ................
- SHLL \[/] $ mdump 0x02000000 32
+ SHLL [/] $ mdump 0x02000000 32
0x02000000A1 48 00 00 29 00 80 33-81 C5 22 BC A6 10 21 00 .H..)..3.."...!.
0x02000010A1 48 00 00 29 00 80 33-81 C5 22 BC A6 10 21 01 .H..)..3.."...!.
- SHLL \[/] $ mdump 0x02001000 32
+ SHLL [/] $ mdump 0x02001000 32
0x0200100003 00 80 00 82 10 60 00-81 98 40 00 83 48 00 00 ......`.....H..
0x0200101084 00 60 01 84 08 A0 07-86 10 20 01 87 28 C0 02 ..`....... ..(..
@@ -81,52 +88,55 @@ The following is an example of how to use ``mdump``:
.. index:: CONFIGURE_SHELL_NO_COMMAND_MDUMP
.. index:: CONFIGURE_SHELL_COMMAND_MDUMP
-This command is included in the default shell command set.
-When building a custom command set, define``CONFIGURE_SHELL_COMMAND_MDUMP`` to have this
+This command is included in the default shell command set. When building a
+custom command set, define ``CONFIGURE_SHELL_COMMAND_MDUMP`` to have this
command included.
-This command can be excluded from the shell command set by
-defining ``CONFIGURE_SHELL_NO_COMMAND_MDUMP`` when all
-shell commands have been configured.
+This command can be excluded from the shell command set by defining
+``CONFIGURE_SHELL_NO_COMMAND_MDUMP`` when all shell commands have been
+configured.
**PROGRAMMING INFORMATION:**
.. index:: rtems_shell_rtems_main_mdump
-The ``mdump`` is implemented by a C language function
-which has the following prototype:
+The ``mdump`` is implemented by a C language function which has the following
+prototype:
+
.. code:: c
int rtems_shell_rtems_main_mdump(
- int argc,
- char \**argv
+ int argc,
+ char **argv
);
-The configuration structure for the ``mdump`` has the
-following prototype:
+The configuration structure for the ``mdump`` has the following prototype:
+
.. code:: c
extern rtems_shell_cmd_t rtems_shell_MDUMP_Command;
+.. _wdump:
+
wdump - display contents of memory (word)
-----------------------------------------
.. index:: wdump
**SYNOPSYS:**
-.. code:: c
+.. code:: shell
- wdump \[address \[length]]
+ wdump [address [length]]
**DESCRIPTION:**
-This command displays the contents of memory at the ``address``
-and ``length`` in bytes specified on the command line.
+This command displays the contents of memory at the ``address`` and ``length``
+in bytes specified on the command line.
This command is equivalent to ``mdump address length 2``.
-When ``length`` is not provided, it defaults to ``320`` which
-is twenty lines of output with eight words of output per line.
+When ``length`` is not provided, it defaults to ``320`` which is twenty lines
+of output with eight words of output per line.
When ``address`` is not provided, it defaults to ``0x00000000``.
@@ -142,9 +152,10 @@ program fault.
**EXAMPLES:**
The following is an example of how to use ``wdump``:
-.. code:: c
- SHLL \[/] $ wdump 0x02010000 32
+.. code:: shell
+
+ SHLL [/] $ wdump 0x02010000 32
0x02010000 0201 08D8 0201 08C0-0201 08AC 0201 0874 ...............t
0x02010010 0201 0894 0201 0718-0201 0640 0201 0798 ...............
@@ -153,52 +164,55 @@ The following is an example of how to use ``wdump``:
.. index:: CONFIGURE_SHELL_NO_COMMAND_WDUMP
.. index:: CONFIGURE_SHELL_COMMAND_WDUMP
-This command is included in the default shell command set.
-When building a custom command set, define``CONFIGURE_SHELL_COMMAND_WDUMP`` to have this
+This command is included in the default shell command set. When building a
+custom command set, define ``CONFIGURE_SHELL_COMMAND_WDUMP`` to have this
command included.
-This command can be excluded from the shell command set by
-defining ``CONFIGURE_SHELL_NO_COMMAND_WDUMP`` when all
-shell commands have been configured.
+This command can be excluded from the shell command set by defining
+``CONFIGURE_SHELL_NO_COMMAND_WDUMP`` when all shell commands have been
+configured.
**PROGRAMMING INFORMATION:**
.. index:: rtems_shell_rtems_main_wdump
-The ``wdump`` is implemented by a C language function
-which has the following prototype:
+The ``wdump`` is implemented by a C language function which has the following
+prototype:
+
.. code:: c
int rtems_shell_rtems_main_wdump(
- int argc,
- char \**argv
+ int argc,
+ char **argv
);
-The configuration structure for the ``wdump`` has the
-following prototype:
+The configuration structure for the ``wdump`` has the following prototype:
+
.. code:: c
extern rtems_shell_cmd_t rtems_shell_WDUMP_Command;
+.. _ldump:
+
ldump - display contents of memory (longword)
---------------------------------------------
.. index:: ldump
**SYNOPSYS:**
-.. code:: c
+.. code:: shell
- ldump \[address \[length]]
+ ldump [address [length]]
**DESCRIPTION:**
-This command displays the contents of memory at the ``address``
-and ``length`` in bytes specified on the command line.
+This command displays the contents of memory at the ``address`` and ``length``
+in bytes specified on the command line.
This command is equivalent to ``mdump address length 4``.
-When ``length`` is not provided, it defaults to ``320`` which
-is twenty lines of output with four longwords of output per line.
+When ``length`` is not provided, it defaults to ``320`` which is twenty lines
+of output with four longwords of output per line.
When ``address`` is not provided, it defaults to ``0x00000000``.
@@ -214,9 +228,10 @@ program fault.
**EXAMPLES:**
The following is an example of how to use ``ldump``:
-.. code:: c
- SHLL \[/] $ ldump 0x02010000 32
+.. code:: shell
+
+ SHLL [/] $ ldump 0x02010000 32
0x02010000 020108D8 020108C0-020108AC 02010874 ...............t
0x02010010 020 0894 02010718-02010640 02010798 ...............
@@ -225,47 +240,51 @@ The following is an example of how to use ``ldump``:
.. index:: CONFIGURE_SHELL_NO_COMMAND_LDUMP
.. index:: CONFIGURE_SHELL_COMMAND_LDUMP
-This command is included in the default shell command set.
-When building a custom command set, define``CONFIGURE_SHELL_COMMAND_LDUMP`` to have this
+This command is included in the default shell command set. When building a
+custom command set, define ``CONFIGURE_SHELL_COMMAND_LDUMP`` to have this
command included.
-This command can be excluded from the shell command set by
-defining ``CONFIGURE_SHELL_NO_COMMAND_LDUMP`` when all
-shell commands have been configured.
+This command can be excluded from the shell command set by defining
+``CONFIGURE_SHELL_NO_COMMAND_LDUMP`` when all shell commands have been
+configured.
**PROGRAMMING INFORMATION:**
.. index:: rtems_shell_rtems_main_ldump
-The ``ldump`` is implemented by a C language function
-which has the following prototype:
+The ``ldump`` is implemented by a C language function which has the following
+prototype:
+
.. code:: c
int rtems_shell_rtems_main_ldump(
- int argc,
- char \**argv
+ int argc,
+ char **argv
);
-The configuration structure for the ``ldump`` has the
-following prototype:
+The configuration structure for the ``ldump`` has the following prototype:
+
.. code:: c
extern rtems_shell_cmd_t rtems_shell_LDUMP_Command;
+.. _medit:
+
medit - modify contents of memory
---------------------------------
.. index:: medit
**SYNOPSYS:**
-.. code:: c
+.. code:: shell
- medit address value1 \[value2 ... valueN]
+ medit address value1 [value2 ... valueN]
**DESCRIPTION:**
-This command is used to modify the contents of the memory starting
-at ``address`` using the octets specified by the parameters``value1`` through ``valueN``.
+This command is used to modify the contents of the memory starting at
+``address`` using the octets specified by the parameters``value1`` through
+``valueN``.
**EXIT STATUS:**
@@ -279,13 +298,14 @@ program fault.
**EXAMPLES:**
The following is an example of how to use ``medit``:
-.. code:: c
- SHLL \[/] $ mdump 0x02000000 32
+.. code:: shell
+
+ SHLL [/] $ mdump 0x02000000 32
0x02000000 A1 48 00 00 29 00 80 33-81 C5 22 BC A6 10 21 00 .H..)..3.."...!.
0x02000010 A1 48 00 00 29 00 80 33-81 C5 22 BC A6 10 21 01 .H..)..3.."...!.
- SHLL \[/] $ medit 0x02000000 0x01 0x02 0x03 0x04 0x05 0x06 0x07 0x08 0x09
- SHLL \[/] $ mdump 0x02000000 32
+ SHLL [/] $ medit 0x02000000 0x01 0x02 0x03 0x04 0x05 0x06 0x07 0x08 0x09
+ SHLL [/] $ mdump 0x02000000 32
0x02000000 01 02 03 04 05 06 07 08-09 00 22 BC A6 10 21 00 .........."...!.
0x02000010 A1 48 00 00 29 00 80 33-81 C5 22 BC A6 10 21 01 .H..)..3.."...!.
@@ -294,47 +314,50 @@ The following is an example of how to use ``medit``:
.. index:: CONFIGURE_SHELL_NO_COMMAND_MEDIT
.. index:: CONFIGURE_SHELL_COMMAND_MEDIT
-This command is included in the default shell command set.
-When building a custom command set, define``CONFIGURE_SHELL_COMMAND_MEDIT`` to have this
+This command is included in the default shell command set. When building a
+custom command set, define ``CONFIGURE_SHELL_COMMAND_MEDIT`` to have this
command included.
-This command can be excluded from the shell command set by
-defining ``CONFIGURE_SHELL_NO_COMMAND_MEDIT`` when all
-shell commands have been configured.
+This command can be excluded from the shell command set by defining
+``CONFIGURE_SHELL_NO_COMMAND_MEDIT`` when all shell commands have been
+configured.
**PROGRAMMING INFORMATION:**
.. index:: rtems_shell_rtems_main_medit
-The ``medit`` is implemented by a C language function
-which has the following prototype:
+The ``medit`` is implemented by a C language function which has the following
+prototype:
+
.. code:: c
int rtems_shell_rtems_main_medit(
- int argc,
- char \**argv
+ int argc,
+ char **argv
);
-The configuration structure for the ``medit`` has the
-following prototype:
+The configuration structure for the ``medit`` has the following prototype:
+
.. code:: c
extern rtems_shell_cmd_t rtems_shell_MEDIT_Command;
+.. _mfill:
+
mfill - file memory with pattern
--------------------------------
.. index:: mfill
**SYNOPSYS:**
-.. code:: c
+.. code:: shell
mfill address length value
**DESCRIPTION:**
-This command is used to fill the memory starting at ``address``
-for the specified ``length`` in octets when the specified at``value``.
+This command is used to fill the memory starting at ``address`` for the
+specified ``length`` in octets when the specified at``value``.
**EXIT STATUS:**
@@ -342,28 +365,27 @@ This command returns 0 on success and non-zero if an error is encountered.
**NOTES:**
-Filling a non-existent address range may result in an unrecoverable
-program fault. Similarly overwriting interrupt vector tables, code
-space or critical data areas can be fatal as shown in the example.
+Filling a non-existent address range may result in an unrecoverable program
+fault. Similarly overwriting interrupt vector tables, code space or critical
+data areas can be fatal as shown in the example.
**EXAMPLES:**
-In this example, the address used (``0x23d89a0``) as the base
-address of the filled area is the end of the stack for the
-Idle thread. This address was determined manually using gdb and
-is very specific to this application and BSP. The first command
-in this example is an ``mdump`` to display the initial contents
-of this memory. We see that the first 8 bytes are 0xA5 which is
-the pattern used as a guard by the Stack Checker. On
-the first context switch after the pattern is overwritten
-by the ``mfill`` command, the Stack Checker detect the pattern
-has been corrupted and generates a fatal error.
-.. code:: c
+In this example, the address used (``0x23d89a0``) as the base address of the
+filled area is the end of the stack for the Idle thread. This address was
+determined manually using gdb and is very specific to this application and BSP.
+The first command in this example is an ``mdump`` to display the initial
+contents of this memory. We see that the first 8 bytes are 0xA5 which is the
+pattern used as a guard by the Stack Checker. On the first context switch
+after the pattern is overwritten by the ``mfill`` command, the Stack Checker
+detect the pattern has been corrupted and generates a fatal error.
- SHLL \[/] $ mdump 0x23d89a0 16
+.. code:: shell
+
+ SHLL [/] $ mdump 0x23d89a0 16
0x023D89A0 A5 A5 A5 A5 A5 A5 A5 A5-FE ED F0 0D 0B AD 0D 06 ................
- SHLL \[/] $ mfill 0x23d89a0 13 0x5a
- SHLL \[/] $ BLOWN STACK!!! Offending task(0x23D4418): id=0x09010001; name=0x0203D908
+ SHLL [/] $ mfill 0x23d89a0 13 0x5a
+ SHLL [/] $ BLOWN STACK!!! Offending task(0x23D4418): id=0x09010001; name=0x0203D908
stack covers range 0x23D89A0 - 0x23D99AF (4112 bytes)
Damaged pattern begins at 0x023D89A8 and is 16 bytes long
@@ -372,48 +394,51 @@ has been corrupted and generates a fatal error.
.. index:: CONFIGURE_SHELL_NO_COMMAND_MFILL
.. index:: CONFIGURE_SHELL_COMMAND_MFILL
-This command is included in the default shell command set.
-When building a custom command set, define``CONFIGURE_SHELL_COMMAND_MFILL`` to have this
+This command is included in the default shell command set. When building a
+custom command set, define ``CONFIGURE_SHELL_COMMAND_MFILL`` to have this
command included.
-This command can be excluded from the shell command set by
-defining ``CONFIGURE_SHELL_NO_COMMAND_MFILL`` when all
-shell commands have been configured.
+This command can be excluded from the shell command set by defining
+``CONFIGURE_SHELL_NO_COMMAND_MFILL`` when all shell commands have been
+configured.
**PROGRAMMING INFORMATION:**
.. index:: rtems_shell_rtems_main_mfill
-The ``mfill`` is implemented by a C language function
-which has the following prototype:
+The ``mfill`` is implemented by a C language function which has the following
+prototype:
+
.. code:: c
int rtems_shell_rtems_main_mfill(
- int argc,
- char \**argv
+ int argc,
+ char **argv
);
The configuration structure for the ``mfill`` has the
following prototype:
+
.. code:: c
extern rtems_shell_cmd_t rtems_shell_MFILL_Command;
+.. _mmove:
+
mmove - move contents of memory
-------------------------------
.. index:: mmove
**SYNOPSYS:**
-.. code:: c
+.. code:: shell
mmove dst src length
**DESCRIPTION:**
-This command is used to copy the contents of the memory
-starting at ``src`` to the memory located at ``dst``
-for the specified ``length`` in octets.
+This command is used to copy the contents of the memory starting at ``src`` to
+the memory located at ``dst`` for the specified ``length`` in octets.
**EXIT STATUS:**
@@ -426,14 +451,15 @@ NONE
**EXAMPLES:**
The following is an example of how to use ``mmove``:
-.. code:: c
- SHLL \[/] $ mdump 0x023d99a0 16
+.. code:: shell
+
+ SHLL [/] $ mdump 0x023d99a0 16
0x023D99A0 A5 A5 A5 A5 A5 A5 A5 A5-A5 A5 A5 A5 A5 A5 A5 A5 ................
- SHLL \[/] $ mdump 0x02000000 16
+ SHLL [/] $ mdump 0x02000000 16
0x02000000 A1 48 00 00 29 00 80 33-81 C5 22 BC A6 10 21 00 .H..)..3.."...!.
- SHLL \[/] $ mmove 0x023d99a0 0x02000000 13
- SHLL \[/] $ mdump 0x023d99a0 16
+ SHLL [/] $ mmove 0x023d99a0 0x02000000 13
+ SHLL [/] $ mdump 0x023d99a0 16
0x023D99A0 A1 48 00 00 29 00 80 33-81 C5 22 BC A6 A5 A5 A5 .H..)..3..".....
**CONFIGURATION:**
@@ -441,48 +467,51 @@ The following is an example of how to use ``mmove``:
.. index:: CONFIGURE_SHELL_NO_COMMAND_MMOVE
.. index:: CONFIGURE_SHELL_COMMAND_MMOVE
-This command is included in the default shell command set.
-When building a custom command set, define``CONFIGURE_SHELL_COMMAND_MMOVE`` to have this
+This command is included in the default shell command set. When building a
+custom command set, define ``CONFIGURE_SHELL_COMMAND_MMOVE`` to have this
command included.
-This command can be excluded from the shell command set by
-defining ``CONFIGURE_SHELL_NO_COMMAND_MMOVE`` when all
-shell commands have been configured.
+This command can be excluded from the shell command set by defining
+``CONFIGURE_SHELL_NO_COMMAND_MMOVE`` when all shell commands have been
+configured.
**PROGRAMMING INFORMATION:**
.. index:: rtems_shell_rtems_main_mmove
-The ``mmove`` is implemented by a C language function
-which has the following prototype:
+The ``mmove`` is implemented by a C language function which has the following
+prototype:
+
.. code:: c
int rtems_shell_rtems_main_mmove(
- int argc,
- char \**argv
+ int argc,
+ char **argv
);
-The configuration structure for the ``mmove`` has the
-following prototype:
+The configuration structure for the ``mmove`` has the following prototype:
+
.. code:: c
extern rtems_shell_cmd_t rtems_shell_MMOVE_Command;
+.. _malloc:
+
malloc - obtain information on C program heap
---------------------------------------------
.. index:: malloc
**SYNOPSYS:**
-.. code:: c
+.. code:: shell
- malloc \[walk]
+ malloc [walk]
**DESCRIPTION:**
This command prints information about the current state of the C Program Heap
-used by the ``malloc()`` family of calls if no or invalid options are passed
-to the command. This includes the following information:
+used by the ``malloc()`` family of calls if no or invalid options are passed to
+the command. This includes the following information:
- Number of free blocks
@@ -518,8 +547,8 @@ to the command. This includes the following information:
- Total number of successful resizes
-When the subcommand ``walk`` is specified, then a heap walk will be
-performed and information about each block is printed out.
+When the subcommand ``walk`` is specified, then a heap walk will be performed
+and information about each block is printed out.
**EXIT STATUS:**
@@ -532,9 +561,10 @@ NONE
**EXAMPLES:**
The following is an example of how to use the ``malloc`` command.
-.. code:: c
- SHLL \[/] $ malloc
+.. code:: shell
+
+ SHLL [/] $ malloc
C Program Heap and RTEMS Workspace are the same.
Number of free blocks: 2
Largest free block: 266207504
@@ -553,7 +583,7 @@ The following is an example of how to use the ``malloc`` command.
Total number of failed allocations: 0
Total number of successful frees: 19
Total number of successful resizes: 0
- SHLL \[/] $ malloc walk
+ SHLL [/] $ malloc walk
malloc walk
PASS[0]: page size 8, min block size 48
area begin 0x00210210, area end 0x0FFFC000
@@ -578,13 +608,13 @@ The following is an example of how to use the ``malloc`` command.
.. index:: CONFIGURE_SHELL_NO_COMMAND_MALLOC
.. index:: CONFIGURE_SHELL_COMMAND_MALLOC
-This command is included in the default shell command set.
-When building a custom command set, define``CONFIGURE_SHELL_COMMAND_MALLOC`` to have this
+This command is included in the default shell command set. When building a
+custom command set, define ``CONFIGURE_SHELL_COMMAND_MALLOC`` to have this
command included.
-This command can be excluded from the shell command set by
-defining ``CONFIGURE_SHELL_NO_COMMAND_MALLOC`` when all
-shell commands have been configured.
+This command can be excluded from the shell command set by defining
+``CONFIGURE_SHELL_NO_COMMAND_MALLOC`` when all shell commands have been
+configured.
**PROGRAMMING INFORMATION:**
@@ -592,22 +622,16 @@ shell commands have been configured.
The ``malloc`` is implemented by a C language function
which has the following prototype:
+
.. code:: c
int rtems_shell_rtems_main_malloc(
- int argc,
- char \**argv
+ int argc,
+ char **argv
);
-The configuration structure for the ``malloc`` has the
-following prototype:
+The configuration structure for the ``malloc`` has the following prototype:
+
.. code:: c
extern rtems_shell_cmd_t rtems_shell_MALLOC_Command;
-
-.. COMMENT: COPYRIGHT (c) 1988-2008.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-