From bf61a8b14e57ef56e8f5e190e9bdd0ba5db16a6f Mon Sep 17 00:00:00 2001 From: Chris Johns Date: Tue, 8 Nov 2016 21:33:20 +1100 Subject: shell: Update commands to use descriptions. --- shell/memory_commands.rst | 756 ++++++++++++++++++++++------------------------ 1 file changed, 368 insertions(+), 388 deletions(-) (limited to 'shell/memory_commands.rst') diff --git a/shell/memory_commands.rst b/shell/memory_commands.rst index ff0a4bf..ece85ff 100644 --- a/shell/memory_commands.rst +++ b/shell/memory_commands.rst @@ -34,89 +34,90 @@ subsection is dedicated to each of the commands and describes the behavior and configuration of that command as well as providing an example usage. +.. raw:: latex + + \clearpage + .. _mdump: mdump - display contents of memory ---------------------------------- .. index:: mdump -**SYNOPSYS:** - -.. code-block:: shell - - 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. - -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. +SYNOPSYS: + .. code-block:: shell -When ``address`` is not provided, it defaults to ``0x00000000``. + mdump [address [length [size]]] -**EXIT STATUS:** +DESCRIPTION: + This command displays the contents of memory at the ``address`` and + ``length`` in ``size`` byte units specified on the command line. -This command always returns 0 to indicate success. + 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. -**NOTES:** + When ``length`` is not provided, it defaults to ``320`` which is twenty + lines of output with sixteen bytes of output per line. -Dumping memory from a non-existent address may result in an unrecoverable -program fault. + When ``address`` is not provided, it defaults to ``0x00000000``. -**EXAMPLES:** +EXIT STATUS: + This command always returns 0 to indicate success. -The following is an example of how to use ``mdump``: +NOTES: + Dumping memory from a non-existent address may result in an unrecoverable + program fault. -.. code-block:: shell +EXAMPLES: + The following is an example of how to use ``mdump``: - 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 - 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 - 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 ..`....... ..(.. + .. code-block:: shell -**CONFIGURATION:** + 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 + 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 + 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 ..`....... ..(.. .. 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 -command included. +CONFIGURATION: + 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. - -**PROGRAMMING INFORMATION:** + This command can be excluded from the shell command set by defining + ``CONFIGURE_SHELL_NO_COMMAND_MDUMP`` when all shell commands have been + configured. .. index:: rtems_shell_rtems_main_mdump -The ``mdump`` is implemented by a C language function which has the following -prototype: +PROGRAMMING INFORMATION: + The ``mdump`` is implemented by a C language function which has the + following prototype: + + .. code-block:: c -.. code-block:: c + int rtems_shell_rtems_main_mdump( + int argc, + char **argv + ); - int rtems_shell_rtems_main_mdump( - 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-block:: c -.. code-block:: c + extern rtems_shell_cmd_t rtems_shell_MDUMP_Command; - extern rtems_shell_cmd_t rtems_shell_MDUMP_Command; +.. raw:: latex + + \clearpage .. _wdump: @@ -124,75 +125,72 @@ wdump - display contents of memory (word) ----------------------------------------- .. index:: wdump -**SYNOPSYS:** - -.. code-block:: shell - - 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 is equivalent to ``mdump address length 2``. +SYNOPSYS: + .. code-block:: shell -When ``length`` is not provided, it defaults to ``320`` which is twenty lines -of output with eight words of output per line. + wdump [address [length]] -When ``address`` is not provided, it defaults to ``0x00000000``. +DESCRIPTION: + This command displays the contents of memory at the ``address`` and + ``length`` in bytes specified on the command line. -**EXIT STATUS:** + This command is equivalent to ``mdump address length 2``. -This command always returns 0 to indicate success. + When ``length`` is not provided, it defaults to ``320`` which is twenty + lines of output with eight words of output per line. -**NOTES:** + When ``address`` is not provided, it defaults to ``0x00000000``. -Dumping memory from a non-existent address may result in an unrecoverable -program fault. +EXIT STATUS: + This command always returns 0 to indicate success. -**EXAMPLES:** +NOTES: + Dumping memory from a non-existent address may result in an unrecoverable + program fault. -The following is an example of how to use ``wdump``: +EXAMPLES: + The following is an example of how to use ``wdump``: -.. code-block:: shell + .. code-block:: shell - SHLL [/] $ wdump 0x02010000 32 - 0x02010000 0201 08D8 0201 08C0-0201 08AC 0201 0874 ...............t - 0x02010010 0201 0894 0201 0718-0201 0640 0201 0798 ............... - -**CONFIGURATION:** + SHLL [/] $ wdump 0x02010000 32 + 0x02010000 0201 08D8 0201 08C0-0201 08AC 0201 0874 ...............t + 0x02010010 0201 0894 0201 0718-0201 0640 0201 0798 ............... .. 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 -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. +CONFIGURATION: + 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. -**PROGRAMMING INFORMATION:** + This command can be excluded from the shell command set by defining + ``CONFIGURE_SHELL_NO_COMMAND_WDUMP`` when all shell commands have been + configured. .. index:: rtems_shell_rtems_main_wdump -The ``wdump`` is implemented by a C language function which has the following -prototype: +PROGRAMMING INFORMATION: + The ``wdump`` is implemented by a C language function which has the + following prototype: + + .. code-block:: c + + int rtems_shell_rtems_main_wdump( + int argc, + char **argv + ); -.. code-block:: c + The configuration structure for the ``wdump`` has the following prototype: - int rtems_shell_rtems_main_wdump( - int argc, - char **argv - ); + .. code-block:: c -The configuration structure for the ``wdump`` has the following prototype: + extern rtems_shell_cmd_t rtems_shell_WDUMP_Command; -.. code-block:: c +.. raw:: latex - extern rtems_shell_cmd_t rtems_shell_WDUMP_Command; + \clearpage .. _ldump: @@ -200,75 +198,72 @@ ldump - display contents of memory (longword) --------------------------------------------- .. index:: ldump -**SYNOPSYS:** - -.. code-block:: shell - - ldump [address [length]] - -**DESCRIPTION:** - -This command displays the contents of memory at the ``address`` and ``length`` -in bytes specified on the command line. +SYNOPSYS: + .. code-block:: shell -This command is equivalent to ``mdump address length 4``. + ldump [address [length]] -When ``length`` is not provided, it defaults to ``320`` which is twenty lines -of output with four longwords of output per line. +DESCRIPTION: + This command displays the contents of memory at the ``address`` and + ``length`` in bytes specified on the command line. -When ``address`` is not provided, it defaults to ``0x00000000``. + This command is equivalent to ``mdump address length 4``. -**EXIT STATUS:** + When ``length`` is not provided, it defaults to ``320`` which is twenty + lines of output with four longwords of output per line. -This command always returns 0 to indicate success. + When ``address`` is not provided, it defaults to ``0x00000000``. -**NOTES:** +EXIT STATUS: + This command always returns 0 to indicate success. -Dumping memory from a non-existent address may result in an unrecoverable -program fault. +NOTES: + Dumping memory from a non-existent address may result in an unrecoverable + program fault. -**EXAMPLES:** +EXAMPLES: + The following is an example of how to use ``ldump``: -The following is an example of how to use ``ldump``: + .. code-block:: shell -.. code-block:: shell - - SHLL [/] $ ldump 0x02010000 32 - 0x02010000 020108D8 020108C0-020108AC 02010874 ...............t - 0x02010010 020 0894 02010718-02010640 02010798 ............... - -**CONFIGURATION:** + SHLL [/] $ ldump 0x02010000 32 + 0x02010000 020108D8 020108C0-020108AC 02010874 ...............t + 0x02010010 020 0894 02010718-02010640 02010798 ............... .. 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 -command included. +CONFIGURATION: + 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. - -**PROGRAMMING INFORMATION:** + This command can be excluded from the shell command set by defining + ``CONFIGURE_SHELL_NO_COMMAND_LDUMP`` when all shell commands have been + configured. .. index:: rtems_shell_rtems_main_ldump -The ``ldump`` is implemented by a C language function which has the following -prototype: +PROGRAMMING INFORMATION: + The ``ldump`` is implemented by a C language function which has the following + prototype: + + .. code-block:: c -.. code-block:: c + int rtems_shell_rtems_main_ldump( + int argc, + char **argv + ); - int rtems_shell_rtems_main_ldump( - 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-block:: c -.. code-block:: c + extern rtems_shell_cmd_t rtems_shell_LDUMP_Command; - extern rtems_shell_cmd_t rtems_shell_LDUMP_Command; +.. raw:: latex + + \clearpage .. _medit: @@ -276,73 +271,70 @@ medit - modify contents of memory --------------------------------- .. index:: medit -**SYNOPSYS:** - -.. code-block:: shell - - medit address value1 [value2 ... valueN] - -**DESCRIPTION:** +SYNOPSYS: + .. code-block:: shell -This command is used to modify the contents of the memory starting at -``address`` using the octets specified by the parameters``value1`` through -``valueN``. + medit address value1 [value2 ... valueN] -**EXIT STATUS:** +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 returns 0 on success and non-zero if an error is encountered. +EXIT STATUS: + This command returns 0 on success and non-zero if an error is encountered. -**NOTES:** +NOTES: + Dumping memory from a non-existent address may result in an unrecoverable + program fault. -Dumping memory from a non-existent address may result in an unrecoverable -program fault. +EXAMPLES: + The following is an example of how to use ``medit``: -**EXAMPLES:** + .. code-block:: shell -The following is an example of how to use ``medit``: - -.. code-block:: 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 - 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.."...!. - -**CONFIGURATION:** + 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 + 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.."...!. .. 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 -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. +CONFIGURATION: + 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. -**PROGRAMMING INFORMATION:** + This command can be excluded from the shell command set by defining + ``CONFIGURE_SHELL_NO_COMMAND_MEDIT`` when all shell commands have been + configured. .. index:: rtems_shell_rtems_main_medit -The ``medit`` is implemented by a C language function which has the following -prototype: +PROGRAMMING INFORMATION: + The ``medit`` is implemented by a C language function which has the + following prototype: -.. code-block:: c + .. code-block:: c - int rtems_shell_rtems_main_medit( - int argc, - char **argv - ); + int rtems_shell_rtems_main_medit( + 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-block:: c + .. code-block:: c - extern rtems_shell_cmd_t rtems_shell_MEDIT_Command; + extern rtems_shell_cmd_t rtems_shell_MEDIT_Command; + +.. raw:: latex + + \clearpage .. _mfill: @@ -350,80 +342,78 @@ mfill - file memory with pattern -------------------------------- .. index:: mfill -**SYNOPSYS:** - -.. code-block:: shell - - mfill address length value +SYNOPSYS: + .. code-block:: shell -**DESCRIPTION:** + mfill address length value -This command is used to fill the memory starting at ``address`` for the -specified ``length`` in octets when the specified at``value``. +DESCRIPTION: + This command is used to fill the memory starting at ``address`` for the + specified ``length`` in octets when the specified at``value``. -**EXIT STATUS:** +EXIT STATUS: + This command returns 0 on success and non-zero if an error is encountered. -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. -**NOTES:** +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. -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. + .. code-block:: shell -**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-block:: 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 - stack covers range 0x23D89A0 - 0x23D99AF (4112 bytes) - Damaged pattern begins at 0x023D89A8 and is 16 bytes long - -**CONFIGURATION:** + 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 + stack covers range 0x23D89A0 - 0x23D99AF (4112 bytes) + Damaged pattern begins at 0x023D89A8 and is 16 bytes long .. 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 -command included. +CONFIGURATION: + 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. - -**PROGRAMMING INFORMATION:** + This command can be excluded from the shell command set by defining + ``CONFIGURE_SHELL_NO_COMMAND_MFILL`` when all shell commands have been + configured. .. index:: rtems_shell_rtems_main_mfill -The ``mfill`` is implemented by a C language function which has the following -prototype: +PROGRAMMING INFORMATION: + The ``mfill`` is implemented by a C language function which has the + following prototype: + + .. code-block:: c -.. code-block:: c + int rtems_shell_rtems_main_mfill( + int argc, + char **argv + ); - int rtems_shell_rtems_main_mfill( - int argc, - char **argv - ); + The configuration structure for the ``mfill`` has the + following prototype: -The configuration structure for the ``mfill`` has the -following prototype: + .. code-block:: c -.. code-block:: c + extern rtems_shell_cmd_t rtems_shell_MFILL_Command; - extern rtems_shell_cmd_t rtems_shell_MFILL_Command; +.. raw:: latex + + \clearpage .. _mmove: @@ -431,71 +421,68 @@ mmove - move contents of memory ------------------------------- .. index:: mmove -**SYNOPSYS:** - -.. code-block:: shell +SYNOPSYS: + .. code-block:: shell - mmove dst src length + mmove dst src length -**DESCRIPTION:** +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: + This command returns 0 on success and non-zero if an error is encountered. -**EXIT STATUS:** +NOTES: + NONE -This command returns 0 on success and non-zero if an error is encountered. +EXAMPLES: + The following is an example of how to use ``mmove``: -**NOTES:** + .. code-block:: shell -NONE - -**EXAMPLES:** - -The following is an example of how to use ``mmove``: - -.. code-block:: 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 - 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 - 0x023D99A0 A1 48 00 00 29 00 80 33-81 C5 22 BC A6 A5 A5 A5 .H..)..3.."..... - -**CONFIGURATION:** + 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 + 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 + 0x023D99A0 A1 48 00 00 29 00 80 33-81 C5 22 BC A6 A5 A5 A5 .H..)..3.."..... .. 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 -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. +CONFIGURATION: + 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. -**PROGRAMMING INFORMATION:** + This command can be excluded from the shell command set by defining + ``CONFIGURE_SHELL_NO_COMMAND_MMOVE`` when all shell commands have been + configured. .. index:: rtems_shell_rtems_main_mmove -The ``mmove`` is implemented by a C language function which has the following -prototype: +PROGRAMMING INFORMATION: + The ``mmove`` is implemented by a C language function which has the + following prototype: + + .. code-block:: c + + int rtems_shell_rtems_main_mmove( + int argc, + char **argv + ); -.. code-block:: c + The configuration structure for the ``mmove`` has the following prototype: - int rtems_shell_rtems_main_mmove( - int argc, - char **argv - ); + .. code-block:: c -The configuration structure for the ``mmove`` has the following prototype: + extern rtems_shell_cmd_t rtems_shell_MMOVE_Command; -.. code-block:: c +.. raw:: latex - extern rtems_shell_cmd_t rtems_shell_MMOVE_Command; + \clearpage .. _malloc: @@ -503,137 +490,130 @@ malloc - obtain information on C program heap --------------------------------------------- .. index:: malloc -**SYNOPSYS:** +SYNOPSYS: + .. code-block:: shell -.. code-block:: 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: -**DESCRIPTION:** + - Number of free blocks -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: + - Largest free block -- Number of free blocks + - Total bytes free -- Largest free block + - Number of used blocks -- Total bytes free + - Largest used block -- Number of used blocks + - Total bytes used -- Largest used block + - Size of the allocatable area in bytes -- Total bytes used + - Minimum free size ever in bytes -- Size of the allocatable area in bytes + - Maximum number of free blocks ever -- Minimum free size ever in bytes + - Maximum number of blocks searched ever -- Maximum number of free blocks ever + - Lifetime number of bytes allocated -- Maximum number of blocks searched ever + - Lifetime number of bytes freed -- Lifetime number of bytes allocated + - Total number of searches -- Lifetime number of bytes freed + - Total number of successful allocations -- Total number of searches + - Total number of failed allocations -- Total number of successful allocations + - Total number of successful frees -- Total number of failed allocations + - Total number of successful resizes -- Total number of successful frees + When the subcommand ``walk`` is specified, then a heap walk will be + performed and information about each block is printed out. -- Total number of successful resizes +EXIT STATUS: + This command returns 0 on success and non-zero if an error is encountered. -When the subcommand ``walk`` is specified, then a heap walk will be performed -and information about each block is printed out. +NOTES: + NONE -**EXIT STATUS:** +EXAMPLES: + The following is an example of how to use the ``malloc`` command. -This command returns 0 on success and non-zero if an error is encountered. + .. code-block:: shell -**NOTES:** - -NONE - -**EXAMPLES:** - -The following is an example of how to use the ``malloc`` command. - -.. code-block:: shell - - SHLL [/] $ malloc - C Program Heap and RTEMS Workspace are the same. - Number of free blocks: 2 - Largest free block: 266207504 - Total bytes free: 266208392 - Number of used blocks: 167 - Largest used block: 16392 - Total bytes used: 83536 - Size of the allocatable area in bytes: 266291928 - Minimum free size ever in bytes: 266207360 - Maximum number of free blocks ever: 6 - Maximum number of blocks searched ever: 5 - Lifetime number of bytes allocated: 91760 - Lifetime number of bytes freed: 8224 - Total number of searches: 234 - Total number of successful allocations: 186 - Total number of failed allocations: 0 - Total number of successful frees: 19 - Total number of successful resizes: 0 - SHLL [/] $ malloc walk - malloc walk - PASS[0]: page size 8, min block size 48 - area begin 0x00210210, area end 0x0FFFC000 - first block 0x00210214, last block 0x0FFFBFDC - first free 0x00228084, last free 0x00228354 - PASS[0]: block 0x00210214: size 88 - ... - PASS[0]: block 0x00220154: size 144 - PASS[0]: block 0x002201E4: size 168, prev 0x002205BC, next 0x00228354 (= last free) - PASS[0]: block 0x0022028C: size 168, prev_size 168 - ... - PASS[0]: block 0x00226E7C: size 4136 - PASS[0]: block 0x00227EA4: size 408, prev 0x00228084 (= first free), next 0x00226CE4 - PASS[0]: block 0x0022803C: size 72, prev_size 408 - PASS[0]: block 0x00228084: size 648, prev 0x0020F75C (= head), next 0x00227EA4 - PASS[0]: block 0x0022830C: size 72, prev_size 648 - PASS[0]: block 0x00228354: size 266157192, prev 0x002201E4, next 0x0020F75C (= tail) - PASS[0]: block 0x0FFFBFDC: size 4028711480, prev_size 266157192 - -**CONFIGURATION:** + SHLL [/] $ malloc + C Program Heap and RTEMS Workspace are the same. + Number of free blocks: 2 + Largest free block: 266207504 + Total bytes free: 266208392 + Number of used blocks: 167 + Largest used block: 16392 + Total bytes used: 83536 + Size of the allocatable area in bytes: 266291928 + Minimum free size ever in bytes: 266207360 + Maximum number of free blocks ever: 6 + Maximum number of blocks searched ever: 5 + Lifetime number of bytes allocated: 91760 + Lifetime number of bytes freed: 8224 + Total number of searches: 234 + Total number of successful allocations: 186 + Total number of failed allocations: 0 + Total number of successful frees: 19 + Total number of successful resizes: 0 + SHLL [/] $ malloc walk + malloc walk + PASS[0]: page size 8, min block size 48 + area begin 0x00210210, area end 0x0FFFC000 + first block 0x00210214, last block 0x0FFFBFDC + first free 0x00228084, last free 0x00228354 + PASS[0]: block 0x00210214: size 88 + ... + PASS[0]: block 0x00220154: size 144 + PASS[0]: block 0x002201E4: size 168, prev 0x002205BC, next 0x00228354 (= last free) + PASS[0]: block 0x0022028C: size 168, prev_size 168 + ... + PASS[0]: block 0x00226E7C: size 4136 + PASS[0]: block 0x00227EA4: size 408, prev 0x00228084 (= first free), next 0x00226CE4 + PASS[0]: block 0x0022803C: size 72, prev_size 408 + PASS[0]: block 0x00228084: size 648, prev 0x0020F75C (= head), next 0x00227EA4 + PASS[0]: block 0x0022830C: size 72, prev_size 648 + PASS[0]: block 0x00228354: size 266157192, prev 0x002201E4, next 0x0020F75C (= tail) + PASS[0]: block 0x0FFFBFDC: size 4028711480, prev_size 266157192 .. 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 -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. +CONFIGURATION: + 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. -**PROGRAMMING INFORMATION:** + This command can be excluded from the shell command set by defining + ``CONFIGURE_SHELL_NO_COMMAND_MALLOC`` when all shell commands have been + configured. .. index:: rtems_shell_rtems_main_malloc -The ``malloc`` is implemented by a C language function -which has the following prototype: +PROGRAMMING INFORMATION: + The ``malloc`` is implemented by a C language function which has the + following prototype: -.. code-block:: c + .. code-block:: c - int rtems_shell_rtems_main_malloc( - int argc, - char **argv - ); + int rtems_shell_rtems_main_malloc( + 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-block:: c + .. code-block:: c - extern rtems_shell_cmd_t rtems_shell_MALLOC_Command; + extern rtems_shell_cmd_t rtems_shell_MALLOC_Command; -- cgit v1.2.3