source: rtems/doc/shell/memory.t @ 50a50313

4.11
Last change on this file since 50a50313 was 50a50313, checked in by Sebastian Huber <sebastian.huber@…>, on Jan 21, 2015 at 2:22:46 PM

score: Delete superfluous Heap_Statistics::instance

This value depends on the _Heap_Initialize() call sequence and carries
no useful information.

  • Property mode set to 100644
File size: 17.0 KB
Line 
1@c
2@c  COPYRIGHT (c) 1988-2012.
3@c  On-Line Applications Research Corporation (OAR).
4@c  All rights reserved.
5@c
6
7@chapter Memory Commands
8
9@section Introduction
10
11The RTEMS shell has the following memory commands:
12
13@itemize @bullet
14
15@item @code{mdump} - Display contents of memory
16@item @code{wdump} - Display contents of memory (word)
17@item @code{ldump} - Display contents of memory (longword)
18@item @code{medit} - Modify contents of memory
19@item @code{mfill} - File memory with pattern
20@item @code{mmove} - Move contents of memory
21@item @code{malloc} - Obtain information on C Program Heap
22
23@end itemize
24
25@section Commands
26
27This section details the Memory Commands available.  A
28subsection is dedicated to each of the commands and
29describes the behavior and configuration of that
30command as well as providing an example usage.
31
32@c
33@c
34@c
35@page
36@subsection mdump - display contents of memory
37
38@pgindex mdump
39
40@subheading SYNOPSYS:
41
42@example
43mdump [address [length [size]]]
44@end example
45
46@subheading DESCRIPTION:
47
48This command displays the contents of memory at the @code{address}
49and @code{length} in @code{size} byte units specified on the command line.
50
51When @code{size} is not provided, it defaults to @code{1} byte units.
52Values of @code{1}, @code{2}, and @code{4} are valid; all others will
53cause an error to be reported.
54
55When @code{length} is not provided, it defaults to @code{320} which
56is twenty lines of output with sixteen bytes of output per line.
57
58When @code{address} is not provided, it defaults to @code{0x00000000}.
59
60@subheading EXIT STATUS:
61
62This command always returns 0 to indicate success.
63
64@subheading NOTES:
65
66Dumping memory from a non-existent address may result in an unrecoverable
67program fault.
68
69@subheading EXAMPLES:
70
71The following is an example of how to use @code{mdump}:
72
73@smallexample
74SHLL [/] $ mdump 0x10000 32
750x0001000000 00 00 00 00 00 00 00-00 00 00 00 00 00 00 00 ................
760x0001001000 00 00 00 00 00 00 00-00 00 00 00 00 00 00 00 ................
77SHLL [/] $ mdump 0x02000000 32
780x02000000A1 48 00 00 29 00 80 33-81 C5 22 BC A6 10 21 00 .H..)..3.."...!.
790x02000010A1 48 00 00 29 00 80 33-81 C5 22 BC A6 10 21 01 .H..)..3.."...!.
80SHLL [/] $ mdump 0x02001000 32
810x0200100003 00 80 00 82 10 60 00-81 98 40 00 83 48 00 00 ......`...@..H..
820x0200101084 00 60 01 84 08 A0 07-86 10 20 01 87 28 C0 02 ..`....... ..(..
83@end smallexample
84
85@subheading CONFIGURATION:
86
87@findex CONFIGURE_SHELL_NO_COMMAND_MDUMP
88@findex CONFIGURE_SHELL_COMMAND_MDUMP
89
90This command is included in the default shell command set.
91When building a custom command set, define
92@code{CONFIGURE_SHELL_COMMAND_MDUMP} to have this
93command included.
94
95This command can be excluded from the shell command set by
96defining @code{CONFIGURE_SHELL_NO_COMMAND_MDUMP} when all
97shell commands have been configured.
98
99@subheading PROGRAMMING INFORMATION:
100
101@findex rtems_shell_rtems_main_mdump
102
103The @code{mdump} is implemented by a C language function
104which has the following prototype:
105
106@example
107int rtems_shell_rtems_main_mdump(
108  int    argc,
109  char **argv
110);
111@end example
112
113The configuration structure for the @code{mdump} has the
114following prototype:
115
116@example
117extern rtems_shell_cmd_t rtems_shell_MDUMP_Command;
118@end example
119
120@c
121@c
122@c
123@page
124@subsection wdump - display contents of memory (word)
125
126@pgindex wdump
127
128@subheading SYNOPSYS:
129
130@example
131wdump [address [length]]
132@end example
133
134@subheading DESCRIPTION:
135
136This command displays the contents of memory at the @code{address}
137and @code{length} in bytes specified on the command line.
138
139This command is equivalent to @code{mdump address length 2}.
140
141When @code{length} is not provided, it defaults to @code{320} which
142is twenty lines of output with eight words of output per line.
143
144When @code{address} is not provided, it defaults to @code{0x00000000}.
145
146@subheading EXIT STATUS:
147
148This command always returns 0 to indicate success.
149
150@subheading NOTES:
151
152Dumping memory from a non-existent address may result in an unrecoverable
153program fault.
154
155@subheading EXAMPLES:
156
157The following is an example of how to use @code{wdump}:
158
159@smallexample
160SHLL [/] $ wdump 0x02010000 32
1610x02010000 0201 08D8 0201 08C0-0201 08AC 0201 0874 ...............t
1620x02010010 0201 0894 0201 0718-0201 0640 0201 0798 ...........@....
163@end smallexample
164
165@subheading CONFIGURATION:
166
167@findex CONFIGURE_SHELL_NO_COMMAND_WDUMP
168@findex CONFIGURE_SHELL_COMMAND_WDUMP
169
170This command is included in the default shell command set.
171When building a custom command set, define
172@code{CONFIGURE_SHELL_COMMAND_WDUMP} to have this
173command included.
174
175This command can be excluded from the shell command set by
176defining @code{CONFIGURE_SHELL_NO_COMMAND_WDUMP} when all
177shell commands have been configured.
178
179@subheading PROGRAMMING INFORMATION:
180
181@findex rtems_shell_rtems_main_wdump
182
183The @code{wdump} is implemented by a C language function
184which has the following prototype:
185
186@example
187int rtems_shell_rtems_main_wdump(
188  int    argc,
189  char **argv
190);
191@end example
192
193The configuration structure for the @code{wdump} has the
194following prototype:
195
196@example
197extern rtems_shell_cmd_t rtems_shell_WDUMP_Command;
198@end example
199
200@c
201@c
202@c
203@page
204@subsection ldump - display contents of memory (longword)
205
206@pgindex ldump
207
208@subheading SYNOPSYS:
209
210@example
211ldump [address [length]]
212@end example
213
214@subheading DESCRIPTION:
215
216This command displays the contents of memory at the @code{address}
217and @code{length} in bytes specified on the command line.
218
219This command is equivalent to @code{mdump address length 4}.
220
221When @code{length} is not provided, it defaults to @code{320} which
222is twenty lines of output with four longwords of output per line.
223
224When @code{address} is not provided, it defaults to @code{0x00000000}.
225
226@subheading EXIT STATUS:
227
228This command always returns 0 to indicate success.
229
230@subheading NOTES:
231
232Dumping memory from a non-existent address may result in an unrecoverable
233program fault.
234
235@subheading EXAMPLES:
236
237The following is an example of how to use @code{ldump}:
238
239@smallexample
240SHLL [/] $ ldump 0x02010000 32
2410x02010000 020108D8 020108C0-020108AC 02010874 ...............t
2420x02010010 020 0894 02010718-02010640 02010798 ...........@....
243@end smallexample
244
245@subheading CONFIGURATION:
246
247@findex CONFIGURE_SHELL_NO_COMMAND_LDUMP
248@findex CONFIGURE_SHELL_COMMAND_LDUMP
249
250This command is included in the default shell command set.
251When building a custom command set, define
252@code{CONFIGURE_SHELL_COMMAND_LDUMP} to have this
253command included.
254
255This command can be excluded from the shell command set by
256defining @code{CONFIGURE_SHELL_NO_COMMAND_LDUMP} when all
257shell commands have been configured.
258
259@subheading PROGRAMMING INFORMATION:
260
261@findex rtems_shell_rtems_main_ldump
262
263The @code{ldump} is implemented by a C language function
264which has the following prototype:
265
266@example
267int rtems_shell_rtems_main_ldump(
268  int    argc,
269  char **argv
270);
271@end example
272
273The configuration structure for the @code{ldump} has the
274following prototype:
275
276@example
277extern rtems_shell_cmd_t rtems_shell_LDUMP_Command;
278@end example
279
280@c
281@c
282@c
283@page
284@subsection medit - modify contents of memory
285
286@pgindex medit
287
288@subheading SYNOPSYS:
289
290@example
291medit address value1 [value2 ... valueN]
292@end example
293
294@subheading DESCRIPTION:
295
296This command is used to modify the contents of the memory starting
297at @code{address} using the octets specified by the parameters
298@code{value1} through @code{valueN}.
299
300@subheading EXIT STATUS:
301
302This command returns 0 on success and non-zero if an error is encountered.
303
304@subheading NOTES:
305
306Dumping memory from a non-existent address may result in an unrecoverable
307program fault.
308
309@subheading EXAMPLES:
310
311The following is an example of how to use @code{medit}:
312
313@smallexample
314SHLL [/] $ mdump 0x02000000 32
3150x02000000 A1 48 00 00 29 00 80 33-81 C5 22 BC A6 10 21 00 .H..)..3.."...!.
3160x02000010 A1 48 00 00 29 00 80 33-81 C5 22 BC A6 10 21 01 .H..)..3.."...!.
317SHLL [/] $  medit 0x02000000 0x01 0x02 0x03 0x04 0x05 0x06 0x07 0x08 0x09
318SHLL [/] $ mdump 0x02000000 32
3190x02000000 01 02 03 04 05 06 07 08-09 00 22 BC A6 10 21 00 .........."...!.
3200x02000010 A1 48 00 00 29 00 80 33-81 C5 22 BC A6 10 21 01 .H..)..3.."...!.
321@end smallexample
322
323@subheading CONFIGURATION:
324
325@findex CONFIGURE_SHELL_NO_COMMAND_MEDIT
326@findex CONFIGURE_SHELL_COMMAND_MEDIT
327
328This command is included in the default shell command set.
329When building a custom command set, define
330@code{CONFIGURE_SHELL_COMMAND_MEDIT} to have this
331command included.
332
333This command can be excluded from the shell command set by
334defining @code{CONFIGURE_SHELL_NO_COMMAND_MEDIT} when all
335shell commands have been configured.
336
337@subheading PROGRAMMING INFORMATION:
338
339@findex rtems_shell_rtems_main_medit
340
341The @code{medit} is implemented by a C language function
342which has the following prototype:
343
344@example
345int rtems_shell_rtems_main_medit(
346  int    argc,
347  char **argv
348);
349@end example
350
351The configuration structure for the @code{medit} has the
352following prototype:
353
354@example
355extern rtems_shell_cmd_t rtems_shell_MEDIT_Command;
356@end example
357
358@c
359@c
360@c
361@page
362@subsection mfill - file memory with pattern
363
364@pgindex mfill
365
366@subheading SYNOPSYS:
367
368@example
369mfill address length value
370@end example
371
372@subheading DESCRIPTION:
373
374This command is used to fill the memory starting at @code{address}
375for the specified @code{length} in octets when the specified at
376@code{value}.
377
378@subheading EXIT STATUS:
379
380This command returns 0 on success and non-zero if an error is encountered.
381
382@subheading NOTES:
383
384Filling a non-existent address range may result in an unrecoverable
385program fault.  Similarly overwriting interrupt vector tables, code
386space or critical data areas can be fatal as shown in the example.
387
388@subheading EXAMPLES:
389
390In this example, the address used (@code{0x23d89a0}) as the base
391address of the filled area is the end of the stack for the
392Idle thread.  This address was determined manually using gdb and
393is very specific to this application and BSP.  The first command
394in this example is an @code{mdump} to display the initial contents
395of this memory.  We see that the first 8 bytes are 0xA5 which is
396the pattern used as a guard by the Stack Checker.  On
397the first context switch after the pattern is overwritten
398by the  @code{mfill} command, the Stack Checker detect the pattern
399has been corrupted and generates a fatal error.
400
401@smallexample
402SHLL [/] $ mdump 0x23d89a0 16
4030x023D89A0 A5 A5 A5 A5 A5 A5 A5 A5-FE ED F0 0D 0B AD 0D 06 ................
404SHLL [/] $ mfill 0x23d89a0 13 0x5a
405SHLL [/] $ BLOWN STACK!!! Offending task(0x23D4418): id=0x09010001; name=0x0203D908
406  stack covers range 0x23D89A0 - 0x23D99AF (4112 bytes)
407  Damaged pattern begins at 0x023D89A8 and is 16 bytes long
408@end smallexample
409
410@subheading CONFIGURATION:
411
412@findex CONFIGURE_SHELL_NO_COMMAND_MFILL
413@findex CONFIGURE_SHELL_COMMAND_MFILL
414
415This command is included in the default shell command set.
416When building a custom command set, define
417@code{CONFIGURE_SHELL_COMMAND_MFILL} to have this
418command included.
419
420This command can be excluded from the shell command set by
421defining @code{CONFIGURE_SHELL_NO_COMMAND_MFILL} when all
422shell commands have been configured.
423
424@subheading PROGRAMMING INFORMATION:
425
426@findex rtems_shell_rtems_main_mfill
427
428The @code{mfill} is implemented by a C language function
429which has the following prototype:
430
431@example
432int rtems_shell_rtems_main_mfill(
433  int    argc,
434  char **argv
435);
436@end example
437
438The configuration structure for the @code{mfill} has the
439following prototype:
440
441@example
442extern rtems_shell_cmd_t rtems_shell_MFILL_Command;
443@end example
444
445@c
446@c
447@c
448@page
449@subsection mmove - move contents of memory
450
451@pgindex mmove
452
453@subheading SYNOPSYS:
454
455@example
456mmove dst src length
457@end example
458
459@subheading DESCRIPTION:
460
461This command is used to copy the contents of the memory
462starting at @code{src} to the memory located at @code{dst}
463for the specified @code{length} in octets.
464
465@subheading EXIT STATUS:
466
467This command returns 0 on success and non-zero if an error is encountered.
468
469@subheading NOTES:
470
471NONE
472
473@subheading EXAMPLES:
474
475The following is an example of how to use @code{mmove}:
476
477@smallexample
478SHLL [/] $ mdump 0x023d99a0 16
4790x023D99A0 A5 A5 A5 A5 A5 A5 A5 A5-A5 A5 A5 A5 A5 A5 A5 A5 ................
480SHLL [/] $ mdump 0x02000000 16
4810x02000000 A1 48 00 00 29 00 80 33-81 C5 22 BC A6 10 21 00 .H..)..3.."...!.
482SHLL [/] $ mmove 0x023d99a0 0x02000000 13
483SHLL [/] $ mdump 0x023d99a0 16
4840x023D99A0 A1 48 00 00 29 00 80 33-81 C5 22 BC A6 A5 A5 A5 .H..)..3..".....
485@end smallexample
486
487@subheading CONFIGURATION:
488
489@findex CONFIGURE_SHELL_NO_COMMAND_MMOVE
490@findex CONFIGURE_SHELL_COMMAND_MMOVE
491
492This command is included in the default shell command set.
493When building a custom command set, define
494@code{CONFIGURE_SHELL_COMMAND_MMOVE} to have this
495command included.
496
497This command can be excluded from the shell command set by
498defining @code{CONFIGURE_SHELL_NO_COMMAND_MMOVE} when all
499shell commands have been configured.
500
501@subheading PROGRAMMING INFORMATION:
502
503@findex rtems_shell_rtems_main_mmove
504
505The @code{mmove} is implemented by a C language function
506which has the following prototype:
507
508@example
509int rtems_shell_rtems_main_mmove(
510  int    argc,
511  char **argv
512);
513@end example
514
515The configuration structure for the @code{mmove} has the
516following prototype:
517
518@example
519extern rtems_shell_cmd_t rtems_shell_MMOVE_Command;
520@end example
521
522@c
523@c
524@c
525@page
526@subsection malloc - obtain information on C program heap
527
528@pgindex malloc
529
530@subheading SYNOPSYS:
531
532@example
533malloc [walk]
534@end example
535
536@subheading DESCRIPTION:
537
538This command prints information about the current state of the C Program Heap
539used by the @code{malloc()} family of calls if no or invalid options are passed
540to the command.  This includes the following information:
541
542@itemize @bullet
543@item Number of free blocks
544@item Largest free block
545@item Total bytes free
546@item Number of used blocks
547@item Largest used block
548@item Total bytes used
549@item Size of the allocatable area in bytes
550@item Minimum free size ever in bytes
551@item Maximum number of free blocks ever
552@item Maximum number of blocks searched ever
553@item Lifetime number of bytes allocated
554@item Lifetime number of bytes freed
555@item Total number of searches
556@item Total number of successful allocations
557@item Total number of failed allocations
558@item Total number of successful frees
559@item Total number of successful resizes
560@end itemize
561
562When the subcommand @code{walk} is specified, then a heap walk will be
563performed and information about each block is printed out.
564
565@subheading EXIT STATUS:
566
567This command returns 0 on success and non-zero if an error is encountered.
568
569@subheading NOTES:
570
571NONE
572
573@subheading EXAMPLES:
574
575The following is an example of how to use the @code{malloc} command.
576
577@example
578SHLL [/] $ malloc
579C Program Heap and RTEMS Workspace are the same.
580Number of free blocks:                               2
581Largest free block:                          266207504
582Total bytes free:                            266208392
583Number of used blocks:                             167
584Largest used block:                              16392
585Total bytes used:                                83536
586Size of the allocatable area in bytes:       266291928
587Minimum free size ever in bytes:             266207360
588Maximum number of free blocks ever:                  6
589Maximum number of blocks searched ever:              5
590Lifetime number of bytes allocated:              91760
591Lifetime number of bytes freed:                   8224
592Total number of searches:                          234
593Total number of successful allocations:            186
594Total number of failed allocations:                  0
595Total number of successful frees:                   19
596Total number of successful resizes:                  0
597SHLL [/] $ malloc walk
598malloc walk
599PASS[0]: page size 8, min block size 48
600        area begin 0x00210210, area end 0x0FFFC000
601        first block 0x00210214, last block 0x0FFFBFDC
602        first free 0x00228084, last free 0x00228354
603PASS[0]: block 0x00210214: size 88
604...
605PASS[0]: block 0x00220154: size 144
606PASS[0]: block 0x002201E4: size 168, prev 0x002205BC, next 0x00228354 (= last free)
607PASS[0]: block 0x0022028C: size 168, prev_size 168
608...
609PASS[0]: block 0x00226E7C: size 4136
610PASS[0]: block 0x00227EA4: size 408, prev 0x00228084 (= first free), next 0x00226CE4
611PASS[0]: block 0x0022803C: size 72, prev_size 408
612PASS[0]: block 0x00228084: size 648, prev 0x0020F75C (= head), next 0x00227EA4
613PASS[0]: block 0x0022830C: size 72, prev_size 648
614PASS[0]: block 0x00228354: size 266157192, prev 0x002201E4, next 0x0020F75C (= tail)
615PASS[0]: block 0x0FFFBFDC: size 4028711480, prev_size 266157192
616@end example
617
618@subheading CONFIGURATION:
619
620@findex CONFIGURE_SHELL_NO_COMMAND_MALLOC
621@findex CONFIGURE_SHELL_COMMAND_MALLOC
622
623This command is included in the default shell command set.
624When building a custom command set, define
625@code{CONFIGURE_SHELL_COMMAND_MALLOC} to have this
626command included.
627
628This command can be excluded from the shell command set by
629defining @code{CONFIGURE_SHELL_NO_COMMAND_MALLOC} when all
630shell commands have been configured.
631
632@subheading PROGRAMMING INFORMATION:
633
634@findex rtems_shell_rtems_main_malloc
635
636The @code{malloc} is implemented by a C language function
637which has the following prototype:
638
639@example
640int rtems_shell_rtems_main_malloc(
641  int    argc,
642  char **argv
643);
644@end example
645
646The configuration structure for the @code{malloc} has the
647following prototype:
648
649@example
650extern rtems_shell_cmd_t rtems_shell_MALLOC_Command;
651@end example
652
Note: See TracBrowser for help on using the repository browser.