This is Info file bspint.info, produced by Makeinfo version 1.68 from
the input file
/tantor/build/intel-xscale/xscale-010413/i686-pc-linux-gnulibc2.1/src/bsp/doc/bspint.texinfo.

START-INFO-DIR-ENTRY
* Cygnus BSP Internals: (bspint). The Cygnus Board Support Package Internals
END-INFO-DIR-ENTRY

   This file documents the internals of the Cygnus board support
package.

   Copyright 1999 Cygnus Solutions.  Written by Mark Salter.

   Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

   Permission is granted to copy or distribute modified versions of this
manual under the terms of the GPL (for which purpose this text may be
regarded as a program in the language TeX).


File: bspint.info,  Node: Top,  Next: Requirements,  Up: (dir)

Scope of this Document
**********************

   This document describes the Cygnus Board Support Package. It
includes a description of the BSP's architecture, as well as
information on specific implementations of that architecture.

* Menu:

* Requirements::
* Overview::
* Exceptions::
* Board Startup::
* Comm Channels::
* Network Stack::
* System Information::
* Debug Support::
* Miscellaneous API::
* BSP Porting::


File: bspint.info,  Node: Requirements,  Next: Overview,  Prev: Top,  Up: Top

Requirements
************

   The basic requirement of the BSP is to provide embedded runtime
support for the GNU toolchain. This includes:

   * A debug stub to support GDB's remote protocol.

   * A minimal syscall handler and bindings to support newlib (libc).

   * Startup code to support ROMable applications.

   * Startup code to support applications downloaded to RAM.

   In general, this support for the GNU tools in a cross-compilation
embedded environment must be able to support a number of runtime
configurations:

   * User application/OS linked with board support in ROM. This linkage
     may also include debug stub and library support.

   * Standalone debug ROM consisting of board startup code, debug stub
     and library support linked with minimal application to invoke the
     debug stub. User application/OS can be downloaded and debugged in
     RAM by using a remote debugger such as gdb.

   * Same as above, but with the minimal application being replaced by
     a ROM monitor to provide a command line interface for ASM level
     debugging.

   * FLASH boot sector (or maybe small PROM) containing board support
     linked with simple application to support loading/launching a user
     application/OS contained in FLASH.

   * Same as above, but the application in FLASH is a ROM monitor or
     standalone debug stub so that user application/OS can be
     downloaded and debugged in RAM.

   All of the above configurations must be able to support arbitrary
applications with or without an operating system. It is also desireable
to facilitate the porting of this runtime support to proprietary
hardware by requiring only a minimal, well defined set of board
specific code.


File: bspint.info,  Node: Overview,  Next: Exceptions,  Prev: Requirements,  Up: Top

Overview
********

   The overall BSP support is divided into common code, architecture
specific code and board specific code. This structure is represented in
the BSP directory hierarchy.

* Menu:

* Files::
* Naming Conventions::


File: bspint.info,  Node: Files,  Next: Naming Conventions,  Prev: Overview,  Up: Overview

Files
=====

`bsp/common'
     BSP files which are common across all architectures. Among these
     are:

    `breakpoint.c'
          Common bsp breakpoint handling.

    `bsp.c'
          Common bsp startup code.

    `bsp.ld'
          BSP linker script command file.

    `bsp_cache.c'
          BSP cache support.

    `bsp_if.c'
          Miscellaneous BSP support routines.

    `bsp_reset.c'
          Generic reset handling.  Not supported on all platforms.

    `bsplog.c'
          Debug log for internal BSP use.

    `common.mk'
    `common_top.mk'
          Makefile fragment common to all BSP ports.

    `console-io.c'
          Console channel I/O routines.

    `debug-io.c'
          Debug channel I/O routines.

    `gdb-data.c'
          Shared data handling for GDB remote protocol stub.

    `gdb-threads.c'
          Generic support for multithread debugging.

    `gdb.c'
          Generic code for GDB remote protocol stub.

    `generic-mem.c'
          Generic versions of `bsp_memory_read' and `bsp_memory_write'.

    `generic-reg.c'
          Generic versions of `bsp_set_register' and `bsp_get_register'.

    `irq.c'
    `irq-rom.c'
          Common exception/interrupt handling code.

    `main.c'
          Minimal BSP ROM application for standalone gdb stub.

    `net.c'
          High level interface to tcp/ip channel.

    `printf.c'
    `sprintf.c'
    `vprintf.c'
          Stripped down versions of formatting routines.

    `queue.c'
          General circular queue support for use in drivers.

    `shared-data.c'
          Shared data support.

    `syscall.c'
          Common syscall handler.

    `sysinfo.c'
          Declarations and handler for getting system information.

    `threads-syscall.c'
          Pseudo system calls to communicate with a kernel supporting
          gdb thread-aware debugging.

`bsp/syslib'
     BSP files which provide trap bindings for newlib.
    `close.c'
          close() system call.

    `exit.c'
          exit() system call.

    `fstat.c'
          fstat() system call.

    `getpid.c'
          getpid() system call.

    `gettimeofday.c'
          gettimeofday() system call.

    `isatty.c'
          isatty() system call.

    `kill.c'
          kill() system call.

    `lseek.c'
          lseek() system call.

    `open.c'
          open() system call.

    `print.c'
          print() system call.

    `raise.c'
          raise() system call.

    `read.c'
          read() system call.

    `sbrk.c'
          sbrk() system call.

    `times.c'
          times() system call.

    `unlink.c'
          unlink() system call.

    `write.c'
          write() system call.

`bsp/include'
     Internal BSP header files which are common across all
     architectures:
    `bsp-trap.h'
          BSP Syscall definitions.

    `bsp_if.h'
          Internal shared memory interface between RAM based
          applications and ROM based applications.

    `bsp_start.h'
          Generic C startup code as inline functions.

    `bsplog.h'
          General memory-based logging facility.

    `gdb-threads.h'
          Packet processing for thread aware debugging.

    `gdb.h'
          Definitions for GDB remote protocol stub.

    `net.h'
          Network stack interfaces.

    `queue.h'
          General circular queue support for use in drivers.

    `syscall.h'
          General definitions for use by the syscall subsystem.

    `threads-syscall.h'
          Pseudo system calls to communicate with a kernel supporting
          gdb thread-aware debugging.

    `bsp/bsp.h'
          Generic external interface declarations.

    `bsp/dbg-thread-api.h'
          Declarations used in supporting thread aware debugging.

    `bsp/defs.h'
          General definitions used in the BSP.

    `bsp/gdb-data.h'
          Shared memory interface to gdb remote stub.

    `bsp/hex-utils.h'
          Utilities for decoding hexadecimal encoded integers.

`bsp/net'
     Trivial network stack to support BOOTP acquisition of IP address
     and a minimal TCP debug channel.
    `arp.c'
          ARP packet handler.

    `bootp.c'
          Support for getting IP address from BOOTP/DHCP server.

    `cksum.c'
          TCP/IP checksum utility routines.

    `enet.c'
          Low-level generic interface to poll for ethernet packets.

    `icmp.c'
          Respond to incoming PING packets.

    `ip.c'
          Trivial IP packet handler.

    `pktbuf.c'
          Simple allocator for packet buffers.

    `socket.c'
          Interface to TCP sockets.

    `tcp.c'
          Trivial TCP implementation.

    `timers.c'
          Simple polled timer support.

    `udp.c'
          Trivial UDP support.

`bsp/<arch_name>'
     Files which are specific to a specific architecture. There is one
     such directory for each supported architecture.

`bsp/<arch_name>/<board_name>'
     Files which are specific to a specific board of a specific
     architecure.


File: bspint.info,  Node: Naming Conventions,  Prev: Files,  Up: Overview

Naming Conventions
==================

   The interfaces described in this document fall into two broad areas.
First, there is the exported API which may be used internally by the
BSP itself or externally by a user application. This interface works
equally well whether or not the user application is directly linked
with the boot code. That is, an application being debugged in RAM may
use this interface even if the main part of the BSP is in ROM/FLASH.
Secondly, there is the private interface which is used internally and
works only when linked with the main BSP in ROM/FLASH.  A user
application should never need to use this interface as it is intended
to be used between the debug, board, and library support modules as
well as between generic, architecture specific, and board specific
layers of those modules. In general a function name beginning with
`bsp_' is used for exported functions which may be used by a user
application. Function names beginning with `_bsp_' are used by internal
interfaces between generic, architecture specific, and board specific
code.


File: bspint.info,  Node: Exceptions,  Next: Board Startup,  Prev: Overview,  Up: Top

Exceptions
**********

   To be useful, a debug agent such as a gdb stub will need to be able
to take control from an application being debugged. This can be the
result of a program error causing an exception or it can result from
user input over the debug channel. In the latter case, an interrupt
must be generated so that the debug agent can take control from the
application being debugged. In order to support this basic
functionality, the BSP must install exception and interrupt handlers.
Unfortunately, there is seldom a clear distinction between exceptions
which need to be handled by the debug agent and those needed by the user
application. To further complicate matters, it is often the case that
the debug channel interrupt must go through one or more interrupt
controllers which are shared with other system devices. This requires
the BSP to provide an interface which allows exceptions and interrupts
to be shared with the program being debugged.

* Menu:

* Low-level::
* Interrupts::
* High-level::
* Summary::


File: bspint.info,  Node: Low-level,  Next: Interrupts,  Prev: Exceptions,  Up: Exceptions

Low-level Exception Handling
============================

   The BSP provides a consistent model of exception handling which is
independent of the underlying hardware architecture. At the lowest
level, there is a vector table which provides a vector service routine
(`VSR') pointer for each exception which may be generated by the
underlying hardware. On some architectures, this table and the
trampoline code used to dispatch through it may not be necessary. For
instance, the Fujitsu FR30 provides a suitable vector table in
hardware. In addition to the hardware related vectors, the BSP may
define other entries in the VSR table which provide hooks for other
services such as multithread debugging support for embedded OSes.

Default VSR
-----------

   The BSP library provides a default VSR which is installed into the
VSR table by the BSP ROM startup code. This VSR establishes a higher
level exception mechanism which allows chaining of high-level language
exception handlers.


           default VSR entry point
                     |
             switch to BSP stack
            save volatile registers
                     |
          run user exception handler(s).
                     |
           restore volatile registers
          switch back to original stack
                     |
         zero returned from user handler?
                  |     |
                 No    Yes
                  |     |
                  |   Jump to debug agent entry point
                  |
         return from exception

   The user exception handlers are run by calling `_bsp_exc_dispatch'.
*Note _bsp_exc_dispatch::. In the case of an error return from the user
exception handler, the VSR code jumps to the debug agent VSR entry point
which does the following:


            debug VSR entry point
                     |
             switch to BSP stack
             save all registers
                     |
             debug agent handler
                     |
              restore registers
           switch to original stack
                     |
             return from exception

   The exception handling mechanism for invoking the debug agent is very
different from other debug stub implementations where some set of
individual exception vectors are patched and completely taken over by
the debug agent.  The set of vectors which indicate a problem requiring
debug agent intervention is both board and application dependent. This
is not a good approach in all cases. For instance, the application
being debugged may make use of MMU hardware. If the debug agent has
control and tries to access memory, an MMU exception may occur. If the
debug agent has the MMU exception vector patched, then the memory
reference would appear to be an error even in cases where it was a
valid application address. If the application has the MMU exception
vector patched and the memory reference is invalid, then there is no
mechanism for the debug agent to catch that error. This problem is
avoided by always allowing the application exception handler to run and
determine whether or not debugger intervention is needed.

   With some CPU architectures, it may make sense for the BSP to demux
some exceptions into more specific exceptions. For example, the MIPS
architecture has a general exception vector at the hardware level, but
the BSP handler for this exception will determine the more specific
exception cause and provide individual user exception vectors for all
of those possible causes. Other architectures may require more than
just a simple register save before calling the exception handler or
debug agent. The ARM architecture for instance uses a number of
different operating modes, each with a separate stack, for the various
kinds of exceptions. In such cases, the BSP may force the CPU into a
specific mode before calling the debug agent or user vectors.


File: bspint.info,  Node: Interrupts,  Next: High-level,  Prev: Low-level,  Up: Exceptions

Interrupts
==========

   Because the BSP must support interrupts, it must deal with some
number of interrupt controllers. Generally, there are two types of
interrupt controllers.  Those which use a priority scheme and those
which don't. Priority based interrupt controllers typically allow each
interrupt to be assigned a priority number. Interrupts are enabled and
disabled based on their priority level.  Non-priority interrupt
controllers typically enable and disable individual interrupts using a
bitmask. Both types of interrupt control may exist on any given board.
Sometimes an interrupt controller is integrated into the CPU, sometimes
it is external to the CPU and sometimes both are present. This BSP is
only interested in providing a common API to enable or disable
interrupts. The BSP interfaces do not support configuration of interrupt
controllers other than a default initialization. If a BSP client needs
a different configuration, then the BSP may be modified or the client
code outside of the BSP may reconfigure the interrupt system.

* Menu:

* bsp_irq_controller::
* _bsp_install_irq_controller::


File: bspint.info,  Node: bsp_irq_controller,  Next: _bsp_install_irq_controller,  Prev: Interrupts,  Up: Interrupts

   In order for the common BSP code to deal with unknown numbers and
kinds of interrupt controllers, the architecture and board specific
layers must inform the generic BSP code of any interrupt controllers
needed to support a debug channel or error interrupt. The interrupt
controllers are described by a data type and the BSP is informed of
them through an API.

`bsp_irq_controller'
--------------------

     struct bsp_irq_controller {
       /*
        * ID numbers for the first and last irqs handled by this
        * controller.
        */
       short	first;
       short	last;
     
       /*
        * Pointer to array of bsp_vec_t pointers. These are the
        * heads of the linked list of ISRs for each irq handled
        * by this controller.
        */
       bsp_vec_t **vec_list;
     
       /*
        * Pointer to initialization routine which is run once at
        * boot time. This is where the controller is initialized
        * if necessary. This routine also installs a handler to
        * catch events which need to be handled by this controller.
        * For a first level interrupt controller, this is probably
        * an exception. It could be an interrupt handler if this
        * controller chains into another interrupt controller.
        */
       void (*init)(const struct bsp_irq_controller *ic);
     
       /*
        * Pointer to routines used to disable and enable interrupts
        * handled by this controller. The irq_nr passed is relative
        * to the first irq handled by this controller. That is, it
        * will range from zero to (last - first).
        */
       int  (*disable)(const struct bsp_irq_controller *ic, int irq_nr);
       void (*enable)(const struct bsp_irq_controller *ic, int irq_nr);
     };
   *Description*
A minimal representation of an interrupt controller.


File: bspint.info,  Node: _bsp_install_irq_controller,  Prev: bsp_irq_controller,  Up: Interrupts

   It is necessary to provide an API for runtime installation of
interrupt controllers. This allows a single BSP to support several
versions of the same board and to cleanly separate the installation of
architectural interrupt controllers and board-specific controllers.

`_bsp_install_irq_controller'
-----------------------------

   *Synopsis*
     void
     _bsp_install_irq_controller(const struct bsp_irq_controller *IC);
   *Description*
Routine called by architecture and/or board specific initialization
layers to inform the common layer of an interrupt controller. The
pointer passed in must remain valid, therefore it should be a pointer
to a statically declared structure. This routine simply saves the
pointer for use by the common interrupt handling code.


File: bspint.info,  Node: High-level,  Next: Summary,  Prev: Interrupts,  Up: Exceptions

High-level API
==============

   Higher level code needing access to exception handling may install
an exception vector to handle a given exception. C calling conventions
are used for this vector and the amount of context saved is
architecture dependent. Anything that could be destroyed across a C
function call must be saved.

* Menu:

* bsp_handler_t:: Handler protoype.
* bsp_vec_t:: Handler list element.
* bsp_install_vec:: Install a user handler.
* bsp_remove_vec:: Remove a user handler.
* bsp_install_dbg_handler:: Install a debug agent.
* bsp_invoke_dbg_handler:: Invoke the debug agent.
* _bsp_exc_dispatch:: Run user handlers.
* bsp_enable_irq:: Enable an interrupt.
* bsp_disable_irq:: Disable an interrupt.


File: bspint.info,  Node: bsp_handler_t,  Next: bsp_vec_t,  Prev: High-level,  Up: High-level

`bsp_handler_t'
---------------

     typedef int (*bsp_handler_t)(int  EXC_NR,
                                  void *SAVED_REGS)
   *Description*
Protoype for high-level execption and interrupt handlers. The integer
return value is used to determine whether or not the program may
continue without invoking the debug handler as shown above. A zero
value will cause the debug handler to be invoked. A non-zero value
leads to a normal resumption of the interrupted program. EXC_NR
indictates which exception (or interrupt) caused the handler to be
invoked and SAVED_REGS is a pointer to the exception stack frame where
registers are saved.


File: bspint.info,  Node: bsp_vec_t,  Next: bsp_install_vec,  Prev: bsp_handler_t,  Up: High-level

`bsp_vec_t'
-----------

     typedef struct bsp_vec {
       bsp_handler_t  handler;   /* pointer to handler */
       struct bsp_vec *next;     /* for chaining */
     } bsp_vec_t;
   *Description*
Used to create a linked list or interrupt and exception handlers.


File: bspint.info,  Node: bsp_install_vec,  Next: bsp_remove_vec,  Prev: bsp_vec_t,  Up: High-level

`bsp_install_vec'
-----------------

   *Synopsis*
     bsp_vec_t *bsp_install_vec(int VEC_KIND,
                                int VEC_NR,
                                int OP,
                                bsp_vect_t *VEC);
   *Description*
Installs an interrupt or exception  vector chain pointed to by VEC.
VEC_KIND should be `BSP_VEC_EXCEPTION' or `BSP_VEC_INTERRUPT'. VEC_NR
identifies the exception or interrupt. OP should be one of:

`BSP_VEC_REPLACE'
     Replace existing chain.

`BSP_VEC_CHAIN_FIRST'
     Install vector at head of current chain.

`BSP_VEC_CHAIN_LAST'
     Install vector at end of current chain.

   If OP is `BSP_VEC_REPLACE', a pointer to the replaced vector chain
is returned, otherwise the return value is meaningless.

   It is important to note that the caller of `bsp_install_vec' is
responsible for allocating the bsp_vec_t structure. This structure must
be reserved for use by the BSP until bsp_remove_vec is called. This was
done this way to keep the BSP from having to reserve a pool of memory
of uncertain size to support a memory allocator for the structures.
That is, memory is only allocated for those exceptions and interrupts
which are actually used.


File: bspint.info,  Node: bsp_remove_vec,  Next: bsp_install_dbg_handler,  Prev: bsp_install_vec,  Up: High-level

`bsp_remove_vec'
----------------

   *Synopsis*
     void
     bsp_remove_vec(int        VEC_KIND,
                    int        VEC_NR,
                    bsp_vect_t *VEC);
   *Description*
Remove the vector pointed to by VEC from and interrupt or exception
chain. VEC_KIND should be `BSP_VEC_EXCEPTION' or `BSP_VEC_INTERRUPT'.
VEC_NR identifies the exception or interrupt.


File: bspint.info,  Node: bsp_install_dbg_handler,  Next: bsp_invoke_dbg_handler,  Prev: bsp_remove_vec,  Up: High-level

`bsp_install_dbg_handler'
-------------------------

   *Synopsis*
     bsp_handler_t
     bsp_install_dbg_handler(bsp_handler_t NEW_HANDLER)
   *Description*
This routine installs NEW_HANDLER as the current debug handler and
returns the previous handler.


File: bspint.info,  Node: bsp_invoke_dbg_handler,  Next: _bsp_exc_dispatch,  Prev: bsp_install_dbg_handler,  Up: High-level

`bsp_invoke_dbg_handler'
------------------------

   *Synopsis*
     void
     bsp_invoke_dbg_handler(int  EXCEPTION_NUMBER,
                            void *SAVED_REGS)
   *Description*
This routine calls the debug handler vector directly from a user
exception or interrupt handler. This may be desireable because some
boards use an interrupt line to signal a bus error. If the interrupt
handler simply returned indicating an error, the debug agent would
report a SIGINT. This could be confusing, so the bus error interrupt
handler could use this routine to invoke the debug handler with a
special EXCEPTION_NUMBER to indicate a bus error.


File: bspint.info,  Node: _bsp_exc_dispatch,  Next: bsp_enable_irq,  Prev: bsp_invoke_dbg_handler,  Up: High-level

`_bsp_exc_dispatch'
-------------------

   *Synopsis*
     int
     _bsp_exc_dispatch(int  EXC_NR,
                       void *SAVED_REGS)
   *Description*
This routine provides a common API which low-level exception handlers
may use to invoke user exception handlers. Each installed user handler
for the given exception EXC_NR is called in turn until one returns a
non-zero value or no more handlers exist. If there are no handlers
installed or none of the handlers installed return a non-zero value,
this routine will return zero. If a called user handler returns a
non-zero value, this routine returns a non-zero value.


File: bspint.info,  Node: bsp_enable_irq,  Next: bsp_disable_irq,  Prev: _bsp_exc_dispatch,  Up: High-level

`bsp_enable_irq'
----------------

   *Synopsis*
     void
     bsp_enable_irq(int IRQ_NR);
   *Description*
Enables the interrupt identified by IRQ_NR.


File: bspint.info,  Node: bsp_disable_irq,  Prev: bsp_enable_irq,  Up: High-level

`bsp_disable_irq'
-----------------

   *Synopsis*
     int
     bsp_disable_irq(int IRQ_NR);
   *Description*
Disables the interrupt identified by IRQ_NR. If true if the interrupt
was not already disabled, false if the interrupt was already disabled.


File: bspint.info,  Node: Summary,  Prev: High-level,  Up: Exceptions

Summary
=======

   It should be noted that the user application is in no way forced to
use this exception handling mechanism provided by the BSP. In the vast
majority of cases, there is no reason not to use an exception handler
written in a high level language. There are exceptions (pun intended)
to this. For example, the MIPS architecture uses a software managed TLB
as part of its MMU. A TLB refill exception can be generated relatively
often and in most cases a handler only needs a small number of
instructions to do its work. It would be very inefficient to have to
save and restore registers for such an exception. The BSP ensures that
a user application may simply install its own low level exception
handler over the top of the default handler put in place by the BSP.
On some architectures this is as simple as placing the exception vector
table in RAM. On other architectures, such as the AM30, exception
vectors must be in ROM, so the BSP must provide a hook for low-level
exception handling as well as the normal high level vectors.

   In general, the same is true of interrupts. The application being
debugged or otherwise using the BSP may install its own interrupt
handling. There is a caveat in doing so, however. By replacing the BSP
interrupt handling mechanism, an application will probably break the
ability of the debugger to interrupt a running program asynchronously.


File: bspint.info,  Node: Board Startup,  Next: Comm Channels,  Prev: Exceptions,  Up: Top

Board Startup
*************

   The reset startup code is the minimal amount of assembly code to
enable a higher level language to complete the board initialization. It
is board independent, but has necessary calls to board specific startup
code.  It does the usual things like copying initialized data from ROM
to RAM and zeroing bss. The final initialization step is to call
`bsp_init' to finish initialization and start the application.

* Menu:

* _bsp_init_stack::
* _bsp_init::
* _bsp_init_board_comm::
* _bsp_install_cpu_irq_controllers::
* _bsp_install_board_irq_controllers::
* _bsp_cpu_init::
* _bsp_board_init::


File: bspint.info,  Node: _bsp_init_stack,  Next: _bsp_init,  Prev: Board Startup,  Up: Board Startup

   When the reset startup code first takes control, it is likely that
there is not a usable stack pointer. One of the first things to be done
is to setup a usable stack. This is done by a call to the board
specific assembler routine:

     _bsp_init_stack

   For some CPU architectures, it will not be possible to use a normal
subroutine call because those architectures require a stack to do so.
In these cases, some convention must be established to make this call.
For instance, a prototype BSP for the AM32 (MN103002) jumps to the
`_bsp_init_stack' routine with the return address passed in register a0:

       .extern _bsp_init_stack
       mov _bsp_init_stack,a1
       mov 1f,a0
       jmp (a1)
     1:

   The `_bsp_init_stack' code may also need to perform hardware
initializations to enable bus operations. This is typically the case
for highly integrated MCUs.  It may also be neccessary to probe the
memory subsystem to discover the number and sizes of various memory
regions and caches.

   After `_bsp_init_stack' returns, a valid stack exists and RAM
accesses are possible. The startup code will then copy initialized data
from ROM to RAM and clear the `.bss' area. At this point, the startup
code will execute compiler generated initialization code such as static
constructors. Finally, the startup code will jump to `_bsp_init'.


File: bspint.info,  Node: _bsp_init,  Next: _bsp_init_board_comm,  Prev: _bsp_init_stack,  Up: Board Startup

`_bsp_init'
-----------

   *Synopsis*
     int
     _bsp_init(void)
   *Description*
This routine will call CPU architecture and board-specific routines to
complete initialization before the application `main' routine is
called. _bsp_init calls a number of initialization routines which must
be provided by the CPU or board specific parts of the BSP as noted.


File: bspint.info,  Node: _bsp_init_board_comm,  Next: _bsp_install_cpu_irq_controllers,  Prev: _bsp_init,  Up: Board Startup

`_bsp_init_board_comm'
----------------------

   *Synopsis*
     void
     _bsp_init_board_comm(void)
   *Description*
This board specific routine should set up the board just enough to
enable debugging printfs to work. No interrupts should be used at this
point because the interrupt handling parts of the BSP have not yet been
initialized.


File: bspint.info,  Node: _bsp_install_cpu_irq_controllers,  Next: _bsp_install_board_irq_controllers,  Prev: _bsp_init_board_comm,  Up: Board Startup

`_bsp_install_cpu_irq_controllers'
----------------------------------

   *Synopsis*
     void
     _bsp_install_cpu_irq_controllers(void)
   *Description*
This is the architecture specific routine used to 'install' irq
controllers. It should call `_bsp_install_irq_controller' for each
interrupt controller which is integral to the CPU/MCU.


File: bspint.info,  Node: _bsp_install_board_irq_controllers,  Next: _bsp_cpu_init,  Prev: _bsp_install_cpu_irq_controllers,  Up: Board Startup

`_bsp_install_board_irq_controllers'
------------------------------------

   *Synopsis*
     void
     _bsp_install_board_irq_controllers(void)
   *Description*
This is the board specific routine used to 'install' irq controllers.
It should call `_bsp_install_irq_controller' for each peripheral
interrupt controller on the board.


File: bspint.info,  Node: _bsp_cpu_init,  Next: _bsp_board_init,  Prev: _bsp_install_board_irq_controllers,  Up: Board Startup

`_bsp_cpu_init'
---------------

   *Synopsis*
     void
     _bsp_cpu_init(void)
   *Description*
This CPU specific routine is responsible for any final CPU related
initializations which should be performed before calling `main'.


File: bspint.info,  Node: _bsp_board_init,  Prev: _bsp_cpu_init,  Up: Board Startup

`_bsp_board_init'
-----------------

   *Synopsis*
     void
     _bsp_board_init(void)
   *Description*
This routine is responsible for any final board specific initialization
which should be performed before `main' is called.


File: bspint.info,  Node: Comm Channels,  Next: Network Stack,  Prev: Board Startup,  Up: Top

Communication Channels
**********************

   The BSP provides support for one or more communication channels. One
of these channels is needed for the debug channel. This debug channel
may also serve as the console I/O channel. Alternatively, if more than
one channel is supported for a given board, then a separate channel may
be dedicated as the console I/O channel. If no console channel is
explictly selected, then console I/O is sent to the debug channel. Each
communication channel is identified by a small integer from zero to
N-1, where N is the total number of supported channels. A client of the
BSP can query for information about the communication channels.  *Note
System Information::.

* Menu:

* External Comm API::
* Internal Comm API::
* Comm Interrupts::


File: bspint.info,  Node: External Comm API,  Next: Internal Comm API,  Prev: Comm Channels,  Up: Comm Channels

External Interfaces
===================

   The following routines are the external interfaces to the BSP
communciation channels. These routines may be used by ROM based and RAM
based applications.

* Menu:

* bsp_console_write::
* bsp_console_putc::
* bsp_console_read::
* bsp_console_getc::
* bsp_debug_write::
* bsp_debug_putc::
* bsp_debug_read::
* bsp_debug_getc::
* bsp_debug_irq_disable::
* bsp_debug_irq_enable::
* bsp_set_debug_comm::
* bsp_set_console_comm::
* bsp_set_serial_baud::


File: bspint.info,  Node: bsp_console_write,  Next: bsp_console_putc,  Prev: External Comm API,  Up: External Comm API

`bsp_console_write'
-------------------

   *Synopsis*
     void
     bsp_console_write(const char *P,
                       int        LEN)
   *Description*
Write LEN characters from buffer pointed to by P to the console output
channel.


File: bspint.info,  Node: bsp_console_putc,  Next: bsp_console_read,  Prev: bsp_console_write,  Up: External Comm API

`bsp_console_putc'
------------------

   *Synopsis*
     void
     bsp_console_putc(char CH)
   *Description*
Write character CH to the console output channel.


File: bspint.info,  Node: bsp_console_read,  Next: bsp_console_getc,  Prev: bsp_console_putc,  Up: External Comm API

`bsp_console_read'
------------------

   *Synopsis*
     int
     bsp_console_read(char *P,
                      int  LEN)
   *Description*
Read up to LEN characters from console input channel. Place characters
read into buffer starting at P. This routine will not block, so caller
must be prepared to handle a return value of zero.


File: bspint.info,  Node: bsp_console_getc,  Next: bsp_debug_write,  Prev: bsp_console_read,  Up: External Comm API

`bsp_console_getc'
------------------

   *Synopsis*
     int
     bsp_console_getc(void)
   *Description*
Read and return one character from the console input channel. This
routine will block until a character becomes available.


File: bspint.info,  Node: bsp_debug_write,  Next: bsp_debug_putc,  Prev: bsp_console_getc,  Up: External Comm API

`bsp_console_write'
-------------------

   *Synopsis*
     void
     bsp_debug_write(const char *P,
                     int        LEN)
   *Description*
Write LEN characters from buffer pointed to by P to the debug output
channel.


File: bspint.info,  Node: bsp_debug_putc,  Next: bsp_debug_read,  Prev: bsp_debug_write,  Up: External Comm API

`bsp_debug_putc'
----------------

   *Synopsis*
     void
     bsp_debug_putc(char CH)
   *Description*
Write character CH to the debug output channel.


File: bspint.info,  Node: bsp_debug_read,  Next: bsp_debug_getc,  Prev: bsp_debug_putc,  Up: External Comm API

`bsp_debug_read'
----------------

   *Synopsis*
     int
     bsp_debug_read(char *P,
                    int  LEN)
   *Description*
Read up to LEN characters from debug input channel. Place characters
read into buffer starting at P. This routine will not block, so caller
must be prepared to handle a return value of zero.


File: bspint.info,  Node: bsp_debug_getc,  Next: bsp_debug_irq_disable,  Prev: bsp_debug_read,  Up: External Comm API

`bsp_debug_getc'
----------------

   *Synopsis*
     int
     bsp_debug_getc(void)
   *Description*
Read and return one character from the debug input channel. This
routine will block until a character becomes available.


File: bspint.info,  Node: bsp_debug_irq_disable,  Next: bsp_debug_irq_enable,  Prev: bsp_debug_getc,  Up: External Comm API

`bsp_debug_irq_disable'
-----------------------

   *Synopsis*
     int
     bsp_debug_irq_disable(void)
   *Description*
Disable the receive interrupt for the debug channel. Returns zero if
the interrupt was already disabled, non-zero otherwise.


File: bspint.info,  Node: bsp_debug_irq_enable,  Next: bsp_set_debug_comm,  Prev: bsp_debug_irq_disable,  Up: External Comm API

`bsp_debug_irq_enable'
----------------------

   *Synopsis*
     void
     bsp_debug_irq_enable(void)
   *Description*
Enable the receive interrupt for the debug channel.


File: bspint.info,  Node: bsp_set_debug_comm,  Next: bsp_set_console_comm,  Prev: bsp_debug_irq_enable,  Up: External Comm API

`bsp_set_debug_comm'
--------------------

   *Synopsis*
     int
     bsp_set_debug_comm(int COMM_ID)
   *Description*
Set or get the active debug channel to channel COMM_ID. Return zero if
successful. If COMM_ID is -1, then the current debug channel is
returned.


File: bspint.info,  Node: bsp_set_console_comm,  Next: bsp_set_serial_baud,  Prev: bsp_set_debug_comm,  Up: External Comm API

`bsp_set_console_comm'
----------------------

   *Synopsis*
     int
     bsp_set_console_comm(int COMM_ID)
   *Description*
Set or get the active console channel to channel COMM_ID. Return zero if
successful. If COMM_ID is -1, then the current console channel is
returned.


File: bspint.info,  Node: bsp_set_serial_baud,  Prev: bsp_set_console_comm,  Up: External Comm API

`bsp_set_serial_baud'
---------------------

   *Synopsis*
     int
     bsp_set_serial_baud(int COMM_ID,
                         int BAUD)
   *Description*
Set the speed of channel COMM_ID to BAUD bits per second.  A return
value of zero indicates success. A non-zero return value indicates that
the desired baud rate is unsupported for the given channel. If BAUD is
-1, then the current baudrate is returned.


File: bspint.info,  Node: Internal Comm API,  Next: Comm Interrupts,  Prev: External Comm API,  Up: Comm Channels

Internal Interfaces
===================

   The generic comm handling layer expects the architecture or board
specific code to provide information about the comm channels supported
by the board. This information is provided in a simple global array and
a channel count variable.

* Menu:

* bsp_comm_info::
* bsp_comm_procs::
* bsp_comm_channel::
* _bsp_comm_list::
* _bsp_num_comms::


File: bspint.info,  Node: bsp_comm_info,  Next: bsp_comm_procs,  Prev: Internal Comm API,  Up: Internal Comm API

`bsp_comm_info'
---------------

     struct bsp_comm_info {
       char    *name;
       short   kind;
     #define BSP_COMM_SERIAL 1
     #define BSP_COMM_ENET   2
       short   protocol;
     #define BSP_PROTO_NONE  0
     #define BSP_PROTO_UDP   1
     #define BSP_PROTO_TCP   2
     }
   *Description*
Basic information about a communication channel.


File: bspint.info,  Node: bsp_comm_procs,  Next: bsp_comm_channel,  Prev: bsp_comm_info,  Up: Internal Comm API

`bsp_comm_procs'
----------------

   *Synopsis*
     struct bsp_comm_procs {
       /*
        * Implementation dependent data pointer passed to the
        * following procs when called.
        */
       void *ch_data;
     
       /*
        * Write a buffer of the given length.
        */
       void (*__write)(void *ch_data, const char *buf, int len);
     
       /*
        * Fill a buffer with up to the given length. Returns
        * the actual number of characters read (may be zero).
        */
       int  (*__read)(void *ch_data, char *buf, int len);
     
       /*
        * Send a single character.
        */
       void (*__putc)(void *ch_data, char ch);
     
       /*
        * Read a single character. If no character is immediately
        * available, will block until one becomes available.
        */
       int  (*__getc)(void *ch_data);
     
       /*
        * Catchall comm port control.
        */
       int  (*__control)(void *ch_data, int func, ...);
     
       /*
        * For serial ports, the control function may be used to set
        * and get the current baud rate. Usage:
        *
        *   err = (*__control)(COMMCTL_SETBAUD, int bits_per_second);
        *     err => Zero if successful, -1 if error.
        *
        *   baud = (*__control)(COMMCTL_GETBAUD);
        *     baud => -1 if error, current baud otherwise.
        */
     #define COMMCTL_SETBAUD 0
     #define COMMCTL_GETBAUD 1
     
       /*
        * Install and remove debugger interrupt handlers. These
        * are the receiver interrupt routines which may be used
        * to receive a request to stop a running program.
        */
     #define COMMCTL_INSTALL_DBG_ISR 2
     #define COMMCTL_REMOVE_DBG_ISR  3
     
         /*
          * Disable comm port interrupt. Returns TRUE if
          * interrupt was enabled, FALSE otherwise.
          */
     #define COMMCTL_IRQ_DISABLE 4
         /*
          * Enable comm port interrupt.
          */
     #define COMMCTL_IRQ_ENABLE 5
     };
   *Description*
This is the low-level interface to the communication channel drivers.
All higher level APIs go through these vectors.


File: bspint.info,  Node: bsp_comm_channel,  Next: _bsp_comm_list,  Prev: bsp_comm_procs,  Up: Internal Comm API

`bsp_comm_channel'
------------------

     struct bsp_comm_channel {
       struct bsp_comm_info   info;
       struct bsp_comm_procs  procs;
     };
   *Description*
This structure is a complete description of a single BSP communication
channel.  It contains general information (`bsp_comm_info') and a set
of vectors (`bsp_comm_procs') for performing communication channel
functions.


File: bspint.info,  Node: _bsp_comm_list,  Next: _bsp_num_comms,  Prev: bsp_comm_channel,  Up: Internal Comm API

`_bsp_comm_list'
----------------

   *Synopsis*
     struct bsp_comm_channel _bsp_comm_list[];
   *Description*
Array to hold descriptors of each supported communication channel.


File: bspint.info,  Node: _bsp_num_comms,  Prev: _bsp_comm_list,  Up: Internal Comm API

`_bsp_num_comms'
----------------

   *Synopsis*
     int _bsp_num_comms;
   *Description*
The number of supported communication channels. For each communication
channel, there is an entry in the `_bsp_comm_list' array.


File: bspint.info,  Node: Comm Interrupts,  Prev: Internal Comm API,  Up: Comm Channels

Interrupts
==========

   Each communication channel driver should provide support for a
receive data interrupt so that a debug agent may interrupt a running
program. The exact nature of this "stop" command is private to the
specific debug protocol being used. For the gdb remote remote protocol,
reception of a `^C' character is used to interrupt the running program.

   A non-zero return value indicates that the interrupt handler should
indicate an error condition so that the debug handler can take control
from the running program being debugged. It is the responsibility of
the debug agent to make sure this function pointer is set to point to
the desired protocol specific function.


File: bspint.info,  Node: Network Stack,  Next: System Information,  Prev: Comm Channels,  Up: Top

Network Stack
*************

   A prototype network stack has been created to provide a high speed
channel between host and target boards. This network code relies on a
link level driver provided by the board specific code in the BSP. It
provides very minimal support for `UDP', `TCP', and `BOOTP' services.
The network stack is designed to work in a polled manner with interrupts
disabled. There is minimal interrupt support for received packets so
that a target board will answer `ARP' and `ICMP' (`PING') requests
while an application is running.

* Menu:

* Data Types::
* Packet Buffers::
* Ethernet::
* ARP::
* BOOTP::
* IP::
* UDP::
* TCP::
* Sockets::

