diff options
Diffstat (limited to 'c/src/lib/libbsp/powerpc/beatnik/README')
| -rw-r--r-- | c/src/lib/libbsp/powerpc/beatnik/README | 178 |
1 files changed, 178 insertions, 0 deletions
diff --git a/c/src/lib/libbsp/powerpc/beatnik/README b/c/src/lib/libbsp/powerpc/beatnik/README new file mode 100644 index 0000000000..699f9a5e9d --- /dev/null +++ b/c/src/lib/libbsp/powerpc/beatnik/README @@ -0,0 +1,178 @@ +Some information about this BSP +================================ + +ACKNOWLEDGEMENTS +---------------- +Acknowledgements: + Valuable information was obtained from the following drivers + netbsd: Allegro Networks Inc; Wasabi Systems Inc. + linux: MontaVista, Software, Inc; Chris Zankel, Mark A. Greer. + Matthew Dharm, rabeeh, Manish Lachwani, Ralf Baechle. + rtems: Brookhaven National Laboratory; Shuchen Kate Feng + This BSP also builds on top of the work of others who have contributed + to similar RTEMS (powerpc) BSPs, most notably Eric Valette, Eric Norum + and others. + + In particular, the Author wishes to thank Shuchen Kate Feng (BNL) for many + inspiring discussions and Dayle Kotturi (SLAC) for her contributions, support + and extensive testing. + +LICENSE +------- +See ./LICENSE file. + +Note that not all files that are part of this BSP were written by +me (most notably, the ethernet drivers if_gfe [netbsd port] and +if_em [freebsd port]). Consult individual file headers for copyright +and authorship information. + +BUILD INFO +---------- +(relevant only if you received this BSP unbundled from the RTEMS distribution) + + prepare: + - get up-to date RTEMS release + - untar beatnik.tgz into c/src/lib/libbsp/powerpc + - copy beatnik.cfg into make/custom + - patch c/src/lib/libsp/powerpc/acinclude.ac + - run 'bootstrap' from top directory; make sure RTEMS + autoXXX are found first in your PATH + configure: + - configure with your favorite options. BSP name is 'beatnik' + I recommend passing RTEMS_CFLAGS=-g to 'configure' + +TARGET +------ +Even though this BSP is binary compatible with the MVME5500 it's primary +target was and is the MVME6100 board which in some respects is quite different. +In particular, the discovery chip and the VME bridge exhibit significant +differences. +I am sometimes asked why this BSP provides yet another port of the gfe +and em BSD drivers (which had previously been ported for the mvme5500 +BSP by Shuchen Kate Feng [BNL]). The answer is simply a matter of time: +Once support for the 6100 board was completed I found it easier to use +the set of 'quick-and-dirty' wrappers (found in network/porting) that I had +developed for other projects and to do a new port from scratch using that +framework rather than modifying the mvme5500 BSP's drivers. mvme5500 support was +added to this BSP because we own a few of those boards we occasionally +play with but we don't want to build and support an additional BSP for them. +An important detail -- hardware cache snooping -- was borrowed from +Shuchen Kate Feng's gfe driver port, though. + +HARDWARE SUPPORT +=============== +(some of the headers mentioned below contain more +detailed information) + +NOTE: The BSP supports both, the mvme6100 and the mvme5500 boards. + It detects relevant hardware at run-time. + +CONSOLE: 2 serial devices, UART driver from 'shared' - no surprises + ("/dev/ttyS0", [="/dev/console"], "/dev/ttyS1"). (Only + /dev/ttyS0 is accessible from the front panel.) + +CLOCK: Decrementer, same as other PPC BSPs. (FIXME: a discovery timer + could be used.) + +PIC (interrupt controller) (bsp/irq.h): Marvell hostbridge + does not implement interrupt priorities. The driver supports + priorities in software (masking lower priority lines during + execution of higher priority ISR). I believe the design of the + IRQ subsystem is as efficient as possible with focus on low + latencies. + In addition to the rtems IRQ API, calls are available to + change IRQ priority and to enable/disable interrupts at the PIC. + +EXCEPTIONS: (bspException.h) Routines to install a user callback + for (PPC) exception handling. + +PCI (bsp/pci.h): The BSP hides the fact that there are effectively + two 'root' busses (AKA 'hoses') behind the discovery bridge. + Devices are addressed by bus/slot/function-triples and the PCI + subsystem transparently figures out what hose to use. + In addition to rtems' PCI API, a call is available to scan + all devices executing a user callback on each device. + BSP_pciConfigDump() is a convenience wrapper dumping essential + information (IDs, BAs, IRQ pin/line) to the console or a file. + +MEMORY MAP: CHRP; all addresses (MEM + I/O) read from PCI config. space + are CPU addresses. For sake of portability, drivers should still + use the _IO_BASE, PCI_MEM_BASE, PCI_DRAM_OFFSET constants. + +NVRAM: Address constants are defined in bsp.h + +FLASH (bsp/flashPgm.h): Routines to write flash. Highest level + wrapper writes a file to flash. + NOTE: Writing to flash is disabled by default; + call BSP_flashWriteEnable(). + +I2C (bsp.h, rtems/libi2c.h, libchip/i2c-xxx.h): temp. sensor and eeprom + are available as device files (bsp.h); lower-level interface is + provided by libi2c.h. + NOTE: The I2C devices are not registered and the driver is not + initialized by default. Call BSP_i2c_initialize() to do that; + this will create + /dev/i2c0.vpd-eeprom + /dev/i2c0.usr-eeprom + /dev/i2c0.ds1621 + You can then read the board temperature: + fd = open("/dev/i2c0.ds1621",O_RDONLY) + read(fd,&temp,1) + close(fd); + printf("Board Temp. is %idegC\n",(int)temp); + +VME: (bsp/VME.h, bsp/vme_am_defs.h, bsp/VMEDMA.h). + *always* use VME.h API, if possible; do *not* use chip drivers + (vmeUniverse.h, vmeTsi148.h) directly unless you know what you are + doing (i.e., if you need specific features provided by the particular + chip; currently, both of the mentioned chip drivers expose entry points + that are designed to be compatible). + + VMEConfig.h should not be used by applications as it makes them + dependent on BSP internals. VMEConfig.h is intended to be used + by BSP designers only. + + VME interrupt priorities: the VME bridge(s) do not implement + priorities in hardware. + However, on the 5500/6100 multiple physical interrupt + lines/wires connect the VME bridge to the PIC. Hence, it is possible + to assign the different wires different priorities at the PIC + (see above) and to route VME interrupts to different wires according + to their priority. You need to call driver specific routines + for this (vmeXXXIntRoute()), however (for driver-specific API + consult bsp/vmeUniverse.h, bsp/vmeTsi148.h). + + For VME DMA *always* use the bsp/VMEDMA.h API. DO NOT use + chip-specific features. Applications written using the bsp/VMEDMA.h + API are portable between the UniverseII and the Tsi148. + +HARDWARE TIMERS: (bsp/gt_timer.h). Programmable general-purpose (GPT) and + watchdog timers. Routines are provided to setup, start and stop + GPTs. The setup routine allows for specifying single-shot or periodic + mode and dispatches a user ISR when the GPT expires. + + The watchdog timer - when started - issues a hard-reset of the + board if not 'petted' within a configurable timeout period. + +NETWORK: (bsp/bsp_bsdnet_attach.h). The BSP offers a call to list + all available interfaces (name, description, 'attach'-method) + for the application to make a selection. + Alternatively, there are BSP_auto_network_driver_name and + BSP_auto_enet_attach(), the latter with the capability to configure + the first NIC with a 'live' link status. + All drivers (rewritten 'mve' for the mv64360 NIC (6100) and BSD ports + 'gfe'/'em' (5500)) support the SIOCSIFMEDIA/SIOCGIFMEDIA ioctls + (rtems/rtems_mii_ioctl.h provides helpers to convert strings from/to + control words). + +VPD: (bsp/vpd.h). The board's VPD (vital-product-data such as S/N, + MAC addresses and so forth) can be retrieved. + +BOOTING: BSP has a relocator-header. Clear MSR and jump to the first + instruction in the binary. R3 and R4, if non-null, point to the + start/end of an optional command line string that is copied into + BSP_commandline_string. The BSP is compatible with 'netboot'. + +Have fun. + +-- Till Straumann <strauman@slac.stanford.edu>, 2005-2007. |