source: rtems/bsps/powerpc/beatnik/README @ 00f9faf2

Last change on this file since 00f9faf2 was eb36d11, checked in by Sebastian Huber <sebastian.huber@…>, on Apr 25, 2018 at 1:06:08 PM

bsps: Move documentation, etc. files to bsps

This patch is a part of the BSP source reorganization.

Update #3285.

  • Property mode set to 100644
File size: 8.0 KB
Line 
1Some information about this BSP
2================================
3
4ACKNOWLEDGEMENTS
5----------------
6Acknowledgements:
7 Valuable information was obtained from the following drivers
8   netbsd: Allegro Networks Inc; Wasabi Systems Inc.
9    linux: MontaVista, Software, Inc; Chris Zankel, Mark A. Greer.
10               Matthew Dharm, rabeeh, Manish Lachwani, Ralf Baechle. 
11    rtems: Brookhaven National Laboratory; Shuchen Kate Feng
12 This BSP also builds on top of the work of others who have contributed
13 to similar RTEMS (powerpc) BSPs, most notably Eric Valette, Eric Norum
14 and others.
15
16 In particular, the Author wishes to thank Shuchen Kate Feng (BNL) for many
17 inspiring discussions and Dayle Kotturi (SLAC) for her contributions, support
18 and extensive testing.
19
20LICENSE
21-------
22See ./LICENSE file.
23
24Note that not all files that are part of this BSP were written by
25me (most notably, the ethernet drivers if_gfe [netbsd port] and
26if_em [freebsd port]). Consult individual file headers for copyright
27and authorship information.
28
29BUILD INFO
30----------
31(relevant only if you received this BSP unbundled from the RTEMS distribution)
32
33  prepare:
34  - get up-to date RTEMS release
35  - untar beatnik.tgz into c/src/lib/libbsp/powerpc
36  - copy beatnik.cfg into make/custom
37  - patch c/src/lib/libsp/powerpc/acinclude.ac
38  - run 'bootstrap' from top directory; make sure RTEMS
39    autoXXX are found first in your PATH
40  configure:
41  - configure with your favorite options. BSP name is 'beatnik'
42    I recommend passing RTEMS_CFLAGS=-g to 'configure'
43
44TARGET
45------
46Even though this BSP is binary compatible with the MVME5500 it's primary
47target was and is the MVME6100 board which in some respects is quite different.
48In particular, the discovery chip and the VME bridge exhibit significant
49differences.
50I am sometimes asked why this BSP provides yet another port of the gfe
51and em BSD drivers (which had previously been ported for the mvme5500
52BSP by Shuchen Kate Feng [BNL]). The answer is simply a matter of time:
53Once support for the 6100 board was completed I found it easier to use
54the set of 'quick-and-dirty' wrappers (found in network/porting) that I had
55developed for other projects and to do a new port from scratch using that
56framework rather than modifying the mvme5500 BSP's drivers. mvme5500 support was
57added to this BSP because we own a few of those boards we occasionally
58play with but we don't want to build and support an additional BSP for them.
59An important detail -- hardware cache snooping -- was borrowed from
60Shuchen Kate Feng's gfe driver port, though.
61
62HARDWARE SUPPORT
63===============
64(some of the headers mentioned below contain more
65detailed information)
66
67NOTE:  The BSP supports both, the mvme6100 and the mvme5500 boards.
68       It detects relevant hardware at run-time.
69
70WARNING: It is extremely important that a MOTLoad "waitProbe", "netShut"
71         sequence be executed before booting RTEMS. Otherwise, network
72         interface interrupt handlers installed by MOTLoad may cause memory
73         corruption
74
75CONSOLE: 2 serial devices, UART driver from 'shared' - no surprises
76       ("/dev/ttyS0", [="/dev/console"], "/dev/ttyS1"). (Only
77       /dev/ttyS0 is accessible from the front panel.)
78
79CLOCK: Decrementer, same as other PPC BSPs. (FIXME: a discovery timer
80       could be used.)
81
82PIC (interrupt controller) (bsp/irq.h): Marvell hostbridge
83       does not implement interrupt priorities. The driver supports
84       priorities in software (masking lower priority lines during
85       execution of higher priority ISR). I believe the design of the
86       IRQ subsystem is as efficient as possible with focus on low
87       latencies.
88       In addition to the rtems IRQ API, calls are available to
89       change IRQ priority and to enable/disable interrupts at the PIC.
90
91EXCEPTIONS: (bspException.h) Routines to install a user callback
92       for (PPC) exception handling.
93
94PCI (bsp/pci.h): The BSP hides the fact that there are effectively
95       two 'root' busses (AKA 'hoses') behind the discovery bridge.
96           Devices are addressed by bus/slot/function-triples and the PCI
97           subsystem transparently figures out what hose to use.
98       In addition to rtems' PCI API, a call is available to scan
99       all devices executing a user callback on each device.
100       BSP_pciConfigDump() is a convenience wrapper dumping essential
101       information (IDs, BAs, IRQ pin/line) to the console or a file.
102
103MEMORY MAP: CHRP; all addresses (MEM + I/O) read from PCI config. space
104       are CPU addresses. For sake of portability, drivers should still
105       use the _IO_BASE, PCI_MEM_BASE, PCI_DRAM_OFFSET constants.
106
107NVRAM: Address constants are defined in bsp.h
108
109FLASH (bsp/flashPgm.h): Routines to write flash. Highest level
110      wrapper writes a file to flash.
111          NOTE: Writing to flash is disabled by default;
112                call BSP_flashWriteEnable().
113
114I2C (bsp.h, rtems/libi2c.h, libchip/i2c-xxx.h):  temp. sensor and eeprom
115      are available as device files (bsp.h); lower-level interface is
116      provided by libi2c.h.
117          NOTE: The I2C devices are not registered and the driver is not
118                initialized by default. Call BSP_i2c_initialize() to do that;
119                        this will create
120                                /dev/i2c0.vpd-eeprom
121                                /dev/i2c0.usr-eeprom
122                                /dev/i2c0.ds1621
123                You can then read the board temperature:
124                            fd = open("/dev/i2c0.ds1621",O_RDONLY)
125                                read(fd,&temp,1)
126                                close(fd);
127                                printf("Board Temp. is %idegC\n",(int)temp);
128
129VME: (bsp/VME.h, bsp/vme_am_defs.h, bsp/VMEDMA.h).
130      *always* use VME.h API, if possible; do *not* use chip drivers
131          (vmeUniverse.h, vmeTsi148.h) directly unless you know what you are
132          doing (i.e., if you need specific features provided by the particular
133          chip; currently, both of the mentioned chip drivers expose entry points
134          that are designed to be compatible).
135
136      VMEConfig.h should not be used by applications as it makes them
137      dependent on BSP internals. VMEConfig.h is intended to be used
138          by BSP designers only.
139
140      VME interrupt priorities: the VME bridge(s) do not implement
141      priorities in hardware.
142      However, on the 5500/6100 multiple physical interrupt
143      lines/wires connect the VME bridge to the PIC. Hence, it is possible
144      to assign the different wires different priorities at the PIC
145      (see above) and to route VME interrupts to different wires according
146      to their priority. You need to call driver specific routines
147      for this (vmeXXXIntRoute()), however (for driver-specific API
148          consult bsp/vmeUniverse.h, bsp/vmeTsi148.h).
149
150          For VME DMA *always* use the bsp/VMEDMA.h API. DO NOT use
151          chip-specific features. Applications written using the bsp/VMEDMA.h
152          API are portable between the UniverseII and the Tsi148.
153
154HARDWARE TIMERS: (bsp/gt_timer.h). Programmable general-purpose (GPT) and
155      watchdog timers. Routines are provided to setup, start and stop
156          GPTs. The setup routine allows for specifying single-shot or periodic
157          mode and dispatches a user ISR when the GPT expires.
158
159          The watchdog timer - when started - issues a hard-reset of the
160          board if not 'petted' within a configurable timeout period.
161
162NETWORK: (bsp/bsp_bsdnet_attach.h). The BSP offers a call to list
163      all available interfaces (name, description, 'attach'-method)
164      for the application to make a selection.
165      Alternatively, there are BSP_auto_network_driver_name and
166      BSP_auto_enet_attach(), the latter with the capability to configure
167      the first NIC with a 'live' link status.
168      All drivers (rewritten 'mve' for the mv64360 NIC (6100) and BSD ports
169      'gfe'/'em' (5500)) support the SIOCSIFMEDIA/SIOCGIFMEDIA ioctls
170      (rtems/rtems_mii_ioctl.h provides helpers to convert strings from/to
171      control words).
172
173VPD: (bsp/vpd.h). The board's VPD (vital-product-data such as S/N,
174      MAC addresses and so forth) can be retrieved.
175
176BOOTING: BSP has a relocator-header. Clear MSR and jump to the first
177      instruction in the binary. R3 and R4, if non-null, point to the
178      start/end of an optional command line string that is copied into
179      BSP_commandline_string. The BSP is compatible with 'netboot'.
180
181Have fun.
182
183-- Till Straumann <strauman@slac.stanford.edu>, 2005-2007.
Note: See TracBrowser for help on using the repository browser.