OpenCores
URL https://opencores.org/ocsvn/or1k/or1k/trunk

Subversion Repositories or1k

[/] [or1k/] [trunk/] [ecos-2.0/] [packages/] [redboot/] [v2_0/] [doc/] [redboot.sgml] - Blame information for rev 1765

Details | Compare with Previous | View Log

Line No. Rev Author Line
1 1254 phoenix
2
 
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
 
30
31
 
32
33
RedBoot™ User's Guide
34
35
36
Getting Started with RedBoot
37
Red Bootgetting started
38
RedBoot™ is an acronym for "Red Hat Embedded Debug and Bootstrap",
39
and is the standard embedded system debug/bootstrap environment from Red Hat,
40
replacing the previous generation of debug firmware: CygMon
41
CygMon and GDB stubsGDB
42
stubs. It provides a complete bootstrap environment for a range of embedded
43
operating systems, such as embedded Linux™ and eCos™, and includes facilities
44
such as network downloading and debugging. It also provides a simple flash
45
file system for boot images.
46
RedBoot provides a wide set of tools for downloading and executing programs
47
on embedded target systems, as well as tools for manipulating the target system's
48
environment. It can be used for both product development (debug support) and
49
for end product deployment (flash and network booting).
50
Here are some highlights of RedBoot's capabilities
51
RedBoot’s capabilities:  
52
53
Boot scripting support
54
55
Simple command line interface for RedBoot configuration and
56
management, accessible via serial (terminal) or Ethernet (telnet) 
57
58
Integrated GDB stubs for connection to a host-based debugger
59
via serial or ethernet. (Ethernet connectivity is limited to local network
60
only)
61
62
Attribute Configuration - user control of aspects such as
63
system time and date (if applicable), default Flash image to boot from, default
64
failsafe image, static IP address, etc.
65
66
Configurable and extensible, specifically adapted to the target
67
environment 
68
69
Network bootstrap support including setup and download, via
70
BOOTP, DHCP and TFTP
71
72
X/YModem support for image download via serial
73
74
Power On Self Test
75
76
77
Although RedBoot is derived from eCos, it may be used as a generalized
78
system debug and bootstrap control software for any embedded system and any
79
operating system. For example, with appropriate additions, RedBoot could replace
80
the commonly used BIOS of PC (and certain other) architectures. Red Hat is
81
currently installing RedBoot on all embedded platforms as a standard practice,
82
and RedBoot is now generally included as part of all Red Hat Embedded Linux
83
and eCos ports. Users who specifically wish to use RedBoot with the eCos operating
84
system should refer to the Getting Started with eCos
85
document, which provides information about the portability and extendability
86
of RedBoot in an eCos environment.
87
88
More information about RedBoot on the web
89
The RedBoot Net
90
Distribution web site contains downloadable sources and documentation
91
for all publically released targets, including the latest features and updates.
92
93
94
95
Installing RedBoot
96
installing RedBootgeneral procedures
97
RedBoot installation
98
general proceduresTo install the RedBoot
99
package, follow the procedures detailed in the accompanying README. 
100
Although there are other possible configurations, RedBoot is usually
101
run from the target platform’s flash boot sector or boot ROM, and is
102
designed to run when your system is initially powered on. The method used
103
to install the RedBoot image into non-volatile storage varies from platform
104
to platform. In general, it requires that the image be programmed into flash
105
in situ or programmed into the flash or ROM using a device programmer. In
106
some cases this will be done at manufacturing time; the platform being delivered
107
with RedBoot already in place. In other cases, you will have to program RedBoot
108
into the appropriate device(s) yourself. Installing to flash in situ may require
109
special cabling or interface devices and software provided by the board manufacturer.
110
The details of this installation process for a given platform will be found
111
in Installation and Testing. Once installed, user-specific configuration options
112
may be applied, using the fconfig command,
113
providing that persistent data storage in flash is present in the relevant
114
RedBoot version. See 
115
for details.
116
117
118
User Interface
119
user interface
120
uicliRedBoot
121
provides a command line user interface (CLI). At the minimum, this interface
122
is normally available on a serial port on the platform. If more than one serial
123
interface is available, RedBoot is normally configured to try to use any one
124
of the ports for the CLI. Once command input has been received on one port,
125
that port is used exclusively until the board is reset or the channel
126
is manually changed by the
127
user. If the platform has networking
128
capabilities, the RedBoot CLI is also accessible using the 
129
telnet access protocol. By default, RedBoot runs 
130
telnettelnet on port TCP/9000,
131
but this is configurable and/or settable by the user. 
132
RedBoot also contains a set of GDB stubs
133
GDB "stubs", consisting of code which supports the GDB remote
134
protocol. GDB stub mode is automatically invoked when the '$' character appears
135
anywhere on a command line unless escaped using the '\' character.
136
The platform will remain in GDB
137
stub mode until explicitly disconnected (via the GDB protocol). The GDB stub
138
mode is available regardless of the connection method; either serial or network.
139
Note that if a GDB connection is made via the network, then special care must
140
be taken to preserve that connection when running user code. eCos contains
141
special network sharing code to allow for this situation, and can be used
142
as a model if this methodology is required in other OS environments.
143
144
 
145
146
RedBoot Editing Commands
147
RedBootediting commands
148
editing commands
149
commandseditingRedBoot
150
uses the following line editing commands.
151
NOTE
152
153
In this description, ^A means the character formed
154
by typing the letter “A” while holding down the control key.
155
156
157
Delete (0x7F) or
158
Backspace (0x08)
159
erases the character to the left of the cursor.
160
161
162
^A
163
moves the cursor (insertion point) to the beginning of the line.
164
165
166
^K
167
erases all characters on the line from the cursor to the end.
168
169
170
^E
171
positions the cursor to the end of the line.
172
173
174
^D
175
erases the character under the cursor.
176
177
178
^F
179
moves the cursor one character to the right.
180
181
182
^B
183
moves the cursor one character to the left.
184
185
186
^P
187
replaces the current line by a previous line from the history buffer.
188
A small number of lines
189
can be kept as history.  Using ^P (and ^N), the current line can be replaced
190
by any one of the previously typed lines.
191
192
193
^N
194
replaces the current line by the next line from the history buffer.
195
196
197
In the case of the fconfig
198
command, additional editing commands are possible.
199
As data are entered for this command, the current/previous value
200
will be displayed and the cursor placed at the end of that data.
201
The user may use the editing keys (above) to move around in the data
202
to modify it as appropriate.
203
Additionally, when certain
204
characters are entered at the end of the current value,
205
i.e. entered separately, certain behavior is elicited.
206
207
208
^ (caret) switch to editing the previous item in the
209
fconfig list. If fconfig edits item A, followed by item B,
210
pressing ^ when changing item B, allows you to change item A. This is similar
211
to the up arrow.
212
Note: ^P and ^N do not have the same meaning while editing
213
fconfig data and should not be used.
214
215
216
. (period) stop editing any further items. This does not change
217
the current item.
218
219
Return leaves the value
220
for this item unchanged. Currently it is not possible to step through the
221
value for the start-up script; it must always be retyped.
222
223
224
225
 
226
227
RedBoot Startup Mode
228
229
  RedBootmode
230
  RedBootstartup mode
231
232
 
233
RedBoot can normally be configured to run in a number of startup
234
modes (or just "modes" for short), determining its location of
235
residence and execution:
236
237
 ROM mode
238
 In this mode, RedBoot both resides and executes from
239
 ROM memory (flash or EPROM). This mode is used when there are limited
240
 RAM resources. The flash commands cannot update the region of flash
241
 where the RedBoot image resides. In order to update the RedBoot image
242
 in flash, it is necessary to run a RAM mode instance of
243
 RedBoot.
244
 
245
 
246
 ROMRAM mode
247
 In this mode, RedBoot resides in ROM memory (flash or
248
 EPROM), but is copied to RAM memory before it starts executing. The
249
 RAM footprint is larger than for ROM mode, but there are two
250
 advantages to make up for this: it normally runs faster (relevant
251
 only on slower boards) and it is able to update the flash region
252
 where the image resides.
253
 
254
 
255
 RAM mode
256
 In this mode, RedBoot both resides and executes from
257
 RAM memory. This is used for updating a primary ROM
258
 mode image in situ and sometimes as part of the RedBoot installation
259
 on the board when there's already an existing (non-RedBoot) boot
260
 monitor available.
261
 
262
  You can only use ROM and ROMRAM mode images for booting a
263
 board - a RAM mode image cannot run unless loaded by another ROM
264
 monitor. There is no need for this startup mode if a RedBoot ROMRAM
265
 mode image is the primary boot monitor.  When this startup mode is
266
 programmed into flash (as a convenience as it's fast to load from
267
 flash) it will generally be named as "RedBoot[RAM]" in the FIS
268
 directory.  
269
 
270
271
 
272
The chosen mode has influence on flash and RAM resource usage (see
273
) and the procedure of an in situ update
274
of RedBoot in flash (see ).
275
 
276
The startup mode is controlled by the option CYG_HAL_STARTUP
277
which resides in the platform HAL. Some platforms provide only some of
278
the RAM, ROM, and ROMRAM modes, others provide additional
279
modes.
280
 
281
To see mode of a currently executing RedBoot, issue the
282
version command, which prints the RedBoot banner,
283
including the startup mode (here ROM):
284
RedBoot>version
285
 
286
RedBoot(tm) bootstrap and debug environment [ROM]
287
Non-certified release, version UNKNOWN - built 13:31:57, May 17 2002
288
289
290
 
291
292
 
293
294
RedBoot Resource Usage
295
296
  RedBootresource usage
297
298
 
299
RedBoot takes up both flash and RAM resources depending on its
300
startup mode and number of enabled features. There are also other
301
resources used by RedBoot, such as timers. Platform-specific resources
302
used by RedBoot are listed in the platform specific parts of this
303
manual.
304
 
305
Both flash and RAM resources used by RedBoot depend to some
306
degree on the features enabled in the RedBoot configuration. It is
307
possible to reduce in particular the RAM resources used by RedBoot by
308
removing features that are not needed. Flash resources can also be
309
reduced, but due to the granularity of the flash (the block sizes),
310
reductions in feature size do not always result in flash resource
311
savings.
312
 
313
 
314
315
Flash Resources
316
On many platforms, a ROM mode RedBoot image resides in the first
317
flash sectors, working as the board's primary boot monitor. On these
318
platforms, it is also normal to reserve a similar amount of flash for
319
a secondary RAM mode image, which is used when updating the primary
320
ROM mode image.
321
On other platforms, a ROMRAM mode RedBoot image is used as the
322
primary boot monitor. On these platforms there is not normally
323
reserved space for a RAM mode RedBoot image, since the ROMRAM mode
324
RedBoot is capable of updating the primary boot monitor image.
325
Most platforms also contain a FIS directory (keeping track of
326
available flash space) and a RedBoot config block (containing RedBoot
327
board configuration data).
328
To see the amount of reserved flash memory, run the fis
329
list command:
330
RedBoot> fis list
331
Name              FLASH addr  Mem addr    Length      Entry point
332
RedBoot           0x00000000  0x00000000  0x00020000  0x00000000
333
RedBoot[RAM]      0x00020000  0x06020000  0x00020000  0x060213C0
334
RedBoot config    0x0007F000  0x0007F000  0x00001000  0x00000000
335
FIS directory     0x00070000  0x00070000  0x0000F000  0x00000000
336
337
338
 
339
To save flash resources, use a ROMRAM mode RedBoot, or if using
340
a ROM mode RedBoot, avoid reserving space for the RedBoot[RAM] image
341
(this is done by changing the RedBoot configuration) and download the
342
RAM mode RedBoot whenever it is needed. If the RedBoot image takes up
343
a fraction of an extra flash block, it may be possible to reduce the
344
image size enough to free this block by removing some features.
345
 
346
347
 
348
349
RAM Resources
350
 
351
RedBoot reserves RAM space for its run-time data, and such
352
things as CPU exception/interrupt tables. It normally does so at the
353
bottom of the memory map. It may also reserve space at the top of the
354
memory map for configurable RedBoot features such as the net stack
355
and zlib decompression support.
356
To see the actual amount of reserved space, issue the
357
version command, which prints the RedBoot banner,
358
including the RAM usage:
359
RedBoot> version
360
 
361
RedBoot(tm) bootstrap and debug environment [ROM]
362
Non-certified release, version UNKNOWN - built 13:31:57, May 17 2002
363
 
364
Platform: FooBar (SH 7615)
365
Copyright (C) 2000, 2001, 2002, Red Hat, Inc.
366
 
367
RAM: 0x06000000-0x06080000, 0x06012498-0x06061000 available
368
FLASH: 0x00000000 - 0x00080000, 8 blocks of 0x00010000 bytes each.
369
370
371
 
372
To simplify operations that temporarily need data in free
373
memory, the limits of free RAM are also available as aliases (aligned
374
to the nearest kilo-byte limit). These are named
375
FREEMEMLOFREEMEMLO and
376
FREEMEMHIFREEMEMHI, and can
377
be used in commands like any user defined alias:
378
RedBoot> load -r -b %{FREEMEMLO} file
379
Raw file loaded 0x06012800-0x06013e53, assumed entry at 0x06012800
380
381
382
RedBoot> x -b %{FREEMEMHI}
383
06061000: 86 F5 EB D8 3D 11 51 F2  96 F4 B2 DC 76 76 8F 77  |....=.Q.....vv.w|
384
06061010: E6 55 DD DB F3 75 5D 15  E0 F3 FC D9 C8 73 1D DA  |.U...u]......s..|
385
386
387
 
388
To reduce RedBoot's RAM resource usage, use a ROM mode
389
RedBoot. The RedBoot features that use most RAM are the net stack, the
390
flash support and the gunzip support. These, and other features, can
391
be disabled to reduce the RAM footprint, but obviously at the cost of
392
lost functionality.
393
 
394
395
396
 
397
398
Configuring the RedBoot Environment
399
configuring the RedBoot environment
400
RedBoot environment configuration
401
environment configuration
402
Once installed, RedBoot will operate fairly generically. However,
403
there are some features that can be configured for a particular installation.
404
These depend primarily on whether flash and/or networking
405
supportnetworking and/or flash support
406
flash and/or networking support are available. The remainder
407
of this discussion assumes that support for both of these options is included
408
in RedBoot.
409
410
Target Network Configuration
411
target network configuration
412
network configurationconfiguration
413
secondaryEach node in a networked
414
system needs to have a unique address. Since the network support in RedBoot
415
is based on TCP/IPTCP/IP, this address
416
is an IP (Internet Protocol) address. IP address type
417
There are two ways for a system to “know”
418
its IP address. First, it can be stored locally on the platform. This is known
419
as having a static IP address. Second, the system can use the network itself
420
to discover its IP address. This is known as a dynamic IP address. RedBoot
421
supports this dynamic IP address mode by use of the BOOTP
422
BOOTP (a subset of DHCP
423
DHCP) protocol. In this case, RedBoot will ask the network (actually
424
some generic server on the network) for the IP address to use.
425
NOTE
426
Currently, RedBoot only supports BOOTP. In future releases, DHCP may
427
also be supported, but such support will be limited to additional data items,
428
not lease-based address allocation.
429
430
The choice of IP address typeIP
431
address type is made via the fconfig command
432
fconfig command. Once a selection
433
is made, it will be stored in flash memory. RedBoot only queries the flash
434
configuration information at reset, so any changes will require restarting
435
the platform.
436
Here is an example of the RedBoot fconfig
437
command, showing network addressing:    
438
RedBoot> fconfig -l
439
Run script at boot: false
440
Use BOOTP for network configuration: false
441
Local IP address: 192.168.1.29
442
Default server IP address: 192.168.1.101
443
DNS server IP address: 192.168.1.1
444
GDB connection port: 9000
445
Network debug at boot time: false  
446
In this case, the board has been configured with a static IP address
447
listed as the Local IP address. The default server IP address specifies which
448
network node to communicate with for TFTP service. This address can be overridden
449
directly in the TFTP commandsTFTP
450
commands.
451
The DNS server IP address option
452
controls where RedBoot should make DNS lookupsDNS
453
lookups. A setting of 0.0.0.0 will disable DNS
454
lookups. The DNS server IP address can also be set at runtime.
455
If the selection for Use BOOTP for network configuration
456
 had been true, these IP
457
addresses would be determined at boot time, via the BOOTP protocol. The final
458
number which needs to be configured, regardless of IP address selection mode,
459
is the GDB connection port
460
GDB connection port. RedBoot allows for incoming commands
461
on either the available serial ports or via the network. This port number
462
is the TCP port that RedBoot will use to accept incoming connections.  
463
These connections can be used for GDB sessions, but they can also be
464
used for generic RedBoot commands. In particular, it is possible to communicate
465
with RedBoot via the telnettelnet
466
protocol. For example, on Linux®: 
467
% telnet redboot_board 9000
468
Connected to redboot_board
469
Escape character is ‘^]’.
470
RedBoot>  
471
472
473
Host Network Configuration
474
host network configuration
475
network configurationhost
476
configurationnetworkRedBoot
477
may require three different classes of service from a network host:   
478
479
dynamic IP address allocation, using BOOTP   
480
481
TFTP service for file downloading 
482
483
DNS server for hostname lookups 
484
485
486
Depending on the host system, these services may or may not be available
487
or enabled by default. See your system documentation for more details.
488
In particular, on Red Hat Linux, neither of these services will be configured
489
out of the box. The following will provide a limited explanation of how to
490
set them up. These configuration setups must be done as root
491
 on the host or server machine.
492
493
Enable TFTP on Red Hat Linux 6.2
494
495
TFTPenabling on Red Hat
496
Linux 6.2Red Hat Linux
497
enabling TFTP on version 6.2Ensure that
498
you have the tftp-server RPM package installed. By default, this installs
499
the TFTP server in a disabled state. These steps will enable it:
500
501
Make sure that the following line is uncommented in the control
502
file /etc/inetd.conf tftp dgram   udp     wait    root    /usr/sbin/tcpd      /usr/sbin/in.tftpd
503
504
505
506
If it was necessary to change the line in Step 2, then the inetd
507
server must be restarted, which can be done via the command:    
508
# service inet reload
509
510
511
512
513
Enable TFTP on Red Hat Linux 7 (or newer)
514
515
TFTPenabling on Red Hat
516
Linux 7Red Hat Linux
517
enabling TFTP on version 7Ensure that the
518
xinetd RPM is installed.
519
520
Ensure that the tftp-server RPM is installed.
521
522
Enable TFTP by means of the following: /sbin/chkconfig tftp on
523
Reload the xinetd configuration using the command:
524
 /sbin/service xinetd reload Create the directory /tftpboot
525
using the command mkdir /tftpboot
526
527
528
NOTE
529
Under Red Hat 7 you must address files by absolute pathnames, for example: 
530
/tftpboot/boot.img not /boot.img, as you may have done with
531
other implementations.
532
On systems newer than Red Hat 7 (7.1 and beyond), filenames are once again relative to the
533
/tftpboot directory.
534
535
536
537
538
Enable BOOTP/DHCP server on Red Hat Linux
539
DHCPenabling on Red Hat Linux
540
BOOTP
541
enabling on Red Hat LinuxFirst, ensure that you have
542
the proper package, dhcp (not 
543
dhcpd) installed. The DHCP server provides Dynamic Host Configuration,
544
that is, IP address and other data to hosts on a network. It does this in
545
different ways. Next, there can be a fixed relationship between a certain
546
node and the data, based on that node’s unique Ethernet Station Address
547
(ESA, sometimes called a MAC address). The other possibility is simply to
548
assign addresses that are free. The sample DHCP configuration file shown does
549
both. Refer to the DHCP documentation for more details.
550
Sample DHCP configuration file
551
--------------- /etc/dhcpd.conf -----------------------------
552
default-lease-time 600;
553
max-lease-time 7200;
554
option subnet-mask 255.255.255.0;
555
option broadcast-address 192.168.1.255;
556
option domain-name-servers 198.41.0.4, 128.9.0.107;
557
option domain-name “bogus.com”;
558
allow bootp;
559
shared-network BOGUS {
560
subnet 192.168.1.0 netmask 255.255.255.0 {
561
         option routers 192.168.1.101;
562
         range 192.168.1.1 192.168.1.254;
563
}
564
 }
565
host mbx {
566
         hardware ethernet 08:00:3E:28:79:B8;
567
         fixed-address 192.168.1.20;
568
         filename “/tftpboot/192.168.1.21/zImage”;
569
         default-lease-time -1;
570
         server-name “srvr.bugus.com”;
571
         server-identifier 192.168.1.101;
572
         option host-name “mbx”;
573
} 
574
Once the DHCP package has been installed and the configuration file
575
set up, type:
576
# service dhcpd start
577
578
579
Enable DNS server on Red Hat Linux
580
DNSenabling on Red Hat
581
LinuxFirst, ensure that you have the proper
582
RPM package, caching-nameserver
583
installed. Then change the configuration
584
(in /etc/named.conf) so that the
585
forwarders point to the primary
586
nameservers for your machine, normally using the nameservers listed in
587
/etc/resolv.conf.
588
 
589
</code></pre></td>
      </tr>
      <tr valign="middle">
         <td>590</td>
         <td></td>
         <td></td>
         <td class="code"><pre><code>Sample <filename>/etc/named.conf</filename> for Red Hat Linux 7.x</code></pre></td>
      </tr>
      <tr valign="middle">
         <td>591</td>
         <td></td>
         <td></td>
         <td class="code"><pre><code>
592
 
593
--------------- /etc/named.conf -----------------------------
594
// generated by named-bootconf.pl
595
 
596
options {
597
        directory "/var/named";
598
        /*
599
         * If there is a firewall between you and nameservers you want
600
         * to talk to, you might need to uncomment the query-source
601
         * directive below.  Previous versions of BIND always asked
602
         * questions using port 53, but BIND 8.1 uses an unprivileged
603
         * port by default.
604
         */
605
        // query-source address * port 53;
606
 
607
 
608
        forward first;
609
        forwarders {
610
                212.242.40.3;
611
                212.242.40.51;
612
        };
613
};
614
 
615
//
616
// a caching only nameserver config
617
//
618
// Uncomment the following for Red Hat Linux 7.2 or above:
619
// controls {
620
//         inet 127.0.0.1 allow { localhost; } keys { rndckey; };
621
// };
622
// include "/etc/rndc.key";
623
zone "." IN {
624
        type hint;
625
        file "named.ca";
626
};
627
 
628
zone "localhost" IN {
629
        type master;
630
        file "localhost.zone";
631
        allow-update { none; };
632
};
633
 
634
zone "0.0.127.in-addr.arpa" IN {
635
        type master;
636
        file "named.local";
637
        allow-update { none; };
638
};
639
 
640
641
 
642
Make sure the server is started with the command:
643
# service named start and is
644
started on next reboot with the command
645
# chkconfig named on
646
Finally, you may wish to change
647
/etc/resolv.conf to use
648
127.0.0.1 as the nameserver for your
649
local machine.
650
651
652
RedBoot network gateway
653
RedBoot network gateway
654
network gatewayRedBoot cannot communicate with
655
machines on different subnets because it does not support routing. It always
656
assumes that it can get to an address directly, therefore it always tries
657
to ARP and then send packets directly to that unit. This means that whatever
658
it talks to must be on the same subnet. If you need to talk to a host on a
659
different subnet (even if it's on the same ‘wire’), you need to
660
go through an ARP proxy, providing that there is a Linux box connected to
661
the network which is able to route to the TFTP server. For example: 
662
/proc/sys/net/ipv4/conf/<interface>/proxy_arp where 
663
<interface>should be replaced with whichever network interface
664
is directly connected to the board.
665
666
667
Verification
668
verification (network)
669
network verificationOnce your network setup
670
has been configured, perform simple verification tests as follows: 
671
Reboot your system, to enable the setup, and then try to ‘ping’
672
the target board from a host.
673
674
Once communication has been established, try to ping
675
a host using the RedBoot ping command - both by IP address and hostname.
676
677
Try using the RedBoot load command to download a file
678
from a host.
679
680
681
682
 
683
684
685
 
686
687
688
 
689
690
691
 
692
693

powered by: WebSVN 2.1.0

© copyright 1999-2024 OpenCores.org, equivalent to Oliscience, all rights reserved. OpenCores®, registered trademark.