From fabe6d020fef5bdefe8519c8a1b36c8ef68c6e97 Mon Sep 17 00:00:00 2001 From: Chris Johns Date: Sat, 23 Jan 2016 10:14:53 +1100 Subject: Clean up the memory commands. --- shell/memory_commands.rst | 348 +++++++++++++++++++++++++--------------------- 1 file changed, 186 insertions(+), 162 deletions(-) (limited to 'shell/memory_commands.rst') 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. - -- cgit v1.2.3