From ee3dd9ae991832c66ba0c5543d5180ad87c786b7 Mon Sep 17 00:00:00 2001 From: Joel Sherrill Date: Tue, 20 Oct 1998 16:25:29 +0000 Subject: Significant additions. --- doc/bsp_howto/target.t | 201 ++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 156 insertions(+), 45 deletions(-) (limited to 'doc/bsp_howto') diff --git a/doc/bsp_howto/target.t b/doc/bsp_howto/target.t index e18d70d6e6..8d3ecf0505 100644 --- a/doc/bsp_howto/target.t +++ b/doc/bsp_howto/target.t @@ -6,87 +6,198 @@ @c $Id$ @c -@chapter CPU and Board Dependent Files +@chapter Target Dependent Files -RTEMS divides board dependencies into two parts: +RTEMS has a multi-layered approach to portability. This is done to +maximize the amount of software that can be reused. Much of the +RTEMS source code can be reused on all RTEMS platforms. Other parts +of the executive are specific to hardware in some sense. +RTEMS classifies target dependent code based upon its dependencies +into one of the following categories. @itemize @bullet +@item CPU dependent +@item Board dependent +@item Peripheral dependent +@end itemize -@item the CPU dependant code : it provides basics calls to the kernel, -just as the context switch or the interrupt subroutine implementations. -Sources for the supported families of processors can be found in -$RTEMS_ROOT/c/src/exec/score/cpu. A good starti ng point for a new family -of processors is the no_cpu directory, which holds both prototypes and -descriptions of each needed CPU dependant function. +@subheading CPU Dependent -@item the board dependant code : it includes support for a given board, -such as the board initialization code and drivers for the various devices: +This class of code includes the foundation +routines for the executive proper such as as the context switch and +the interrupt subroutine implementations. Sources for the supported +processor families can be found in @code{$RTEMS_ROOT/c/src/exec/score/cpu}. +A good starting point for a new family of processors is the +@code{no_cpu} directory, which holds both prototypes and +descriptions of each needed CPU dependent function. -@end itemize +CPU dependent code is further subcategorized if the implementation is +dependent on a particular CPU model. For example, the MC68000 and MC68020 +processors are both members of the m68k CPU family but there are significant +differents between these CPU models which RTEMS must take into account. + +@subheading Board Dependent + +This class of code provides the most specific glue between RTEMS and +a particular board. This code is represented by the Board Support Packages +and associated Device Drivers. + +Some BSPs may support multiple board models within a single board family. +This is necessary when the board's vendor supports build variants on a +single base base. For example, the Motorola MVME162 board family has a +a fairly large number of variations based upon the particular CPU model +and the peripherals actually placed on the board. + +@subheading Peripheral Dependent + +This class of code provides a reusable library of peripheral device +drivers which can be tailored easily to a particular board. This +reusable library provides software objects which correspond to standard +controllers. Just as the hardware engineer choose a standard controller +when designing a board, the goal of this library is to let the software +engineer do the same thing. + +@section Questions to Ask -Porting RTEMS on a new board should raise two questions: +Porting RTEMS on a new board should raise some questions: @itemize @bullet -@item is the main board CPU supported ? +@item Does a BSP for this board exist? -@item does a BSP for a similar board exists ? +@item Does a BSP for a similar board exists? + +@item Is the board's CPU supported? @end itemize -If the main board CPU is supported, you will only have do write the Board -Support Package. Otherwise you'll have to write both CPU dependant code -and the BSP. One should always start writing a BSP from a similar one. +If there is already a BSP for your board, then you may already be ready +to start developing application software. You should verify that the +existing BSP provides device drivers for all the peripherals on the board +that your application will be using. For example, the board may have +an Ethernet controller which is not supported by the existing BSP. + +If the BSP does not exist and the board's CPU model is supported, then +you should look at existing BSPs for a close match. This will help +reduce the effort required. It is often possible to reuse device drivers +from BSPs from different CPU families. + +If the board's CPU family is supported but the particular CPU model on +that board is not, then the RTEMS port to that CPU family will have to +be augmented. After this is done, then you can proceed to developing +the new BSP. + +Otherwise you'll have to write both CPU dependent code and the BSP. + +Regardless of the amount of development required, OAR Corporation +offers custom development services to help you use RTEMS. +@ifset use-html +For more information, contact OAR Corporation +at @href{http://www.oarcorp.com,,,http://www.oarcorp.com}. +@end ifset +@ifclear use-html +For more information, contact OAR Corporation +at http://www.oarcorp.com. +@end ifclear + @section CPU Dependent Executive Files -XXX +The CPU dependent files in the RTEMS executive source code are found +in the following directory: + +@example +c/src/exec/score/cpu/CPU +@end example + +where CPU is replcaed with the CPU family name. + +Within each CPU dependent directory inside the executive proper is a +file named @code{CPU.h} which contains information about each of the +supported CPU models within that family. @section CPU Dependent Support Files -XXX +The CPU dependent support files contain routines which aid in the development +of applications using that CPU family. For example, the support routines +may contain standard trap handlers for alignment or floating point exceptions +or device drivers for peripheral controllers found on the CPU itself. +This class of code may be found in the following directory: + +@example +c/src/lib/libcpu/CPU +@end example + +CPU model dependent support code is found in the following directory: + +@example +c/src/lib/libcpu/CPU/CPU_MODEL +@end example @section Board Support Package Structure -The BSPs are kept in the $RTEMS_ROOT/c/src/lib/libbsp directory. They -are filed under the processor family (m68k, powerpc, etc.). A given BSP -consists in the following directories: +The BSPs are all under the c/src/lib/libbsp directory. Below this +directory, there is a subdirectory for each CPU family. Each BSP +is found under the subdirectory for the appropriate processor +family (m68k, powerpc, etc.). In addition, there is source code +available which may be shared across all BSPs regardless of +the CPU family or just across BSPs within a single CPU family. This +results in a BSP using the following directories: + +@example +c/src/lib/libbsp/shared +c/src/lib/libbsp/CPU/shared +c/src/lib/libbsp/CPU/BSP +@end example + +Under each BSP specific directory, you will find a collection of +subdirectories. For commonly provided functionality, the BSPs +follow a convention on subdirectory naming. The following list +describes the commonly found subdirectories under each BSP. @itemize @bullet -@item @b{clock} - -support for the realtime clock, which provides a regular -time basis to the kernel, +@item @b{console}: +is technically the serial driver for the BSP rather +than just a console driver, it deals with the board +UARTs (i.e. serial devices). -@item @b{console} - -rather the serial driver than only a console driver, it -deals with the board UARTs (i.e. serial devices), +@item @b{clock}: +support for the clock tick -- a regular time basis to the kernel. -@item @b{include} - -the include files, +@item @b{timer}: +support of timer devices. -@item @b{startup} - -the board initialization code, +@item @b{rtc}: +support for the hardware real-time clock. -@item @b{timer} - -support of timer devices, +@item @b{nvmem}: +support for non-volatile memory such as EEPROM or Flash. -@item @b{shmsupp} - -support of shared memory in a multiprocessor system, +@item @b{network}: +the Ethernet driver. -@item @b{network} - -the Ethernet driver. +@item @b{shmsupp}: +support of shared memory driver MPCI layer in a multiprocessor system, -@item @b{rtc} - -the real-time clock driver. +@item @b{include}: +include files for this BSP. -@item @b{wrapup} - XXX +@item @b{wrapup}: +bundles all the components necessary to construct the BSP library. @end itemize -Another important element are the makefiles, which have to be provided by -the user. - +The build order of the BSP is determined by the Makefile structure. +This structure is discussed in more detail in the @ref{Makefiles} +chapter. +RTEMS uses the @b{GNU autoconf} automatic configuration package. This +tool specializes the @code{Makefile.in} files at the time that RTEMS +is configured for a specific development host and target. Makefiles +are automatically generated from the @code{Makefile.in} files. It is +necessary for the BSP developer to provide these files. Most of the +time, it is possible to copy the @code{Makefile.in} from another +similar directory and edit it. @b{NOTE:} This manual refers to the gen68340 BSP for numerous concrete examples. You should have a copy of the gen68340 BSP available while @@ -94,7 +205,7 @@ reading this piece of documentation. This BSP is located in the following directory: @example -$RTEMS_ROOT/c/src/lib/libbsp/m68k/gen68340 +c/src/lib/libbsp/m68k/gen68340 @end example Later in this document, the $BSP340_ROOT label will be used -- cgit v1.2.3