From 07b3693f175a0a601a53cba656940aaec8bd9949 Mon Sep 17 00:00:00 2001 From: Joel Sherrill Date: Fri, 28 Aug 1998 13:21:53 +0000 Subject: Base files --- doc/bsp_howto/Makefile | 58 ++++---- doc/bsp_howto/bspstruct.t | 37 +++++ doc/bsp_howto/clock.t | 38 +++++ doc/bsp_howto/console.t | 266 +++++++++++++++++++++++++++++++++++ doc/bsp_howto/init.t | 167 ++++++++++++++++++++++ doc/bsp_howto/intro.t | 24 ++++ doc/bsp_howto/linkcmds.t | 344 ++++++++++++++++++++++++++++++++++++++++++++++ doc/bsp_howto/makefiles.t | 142 +++++++++++++++++++ doc/bsp_howto/target.t | 34 +++++ doc/bsp_howto/timer.t | 66 +++++++++ 10 files changed, 1151 insertions(+), 25 deletions(-) create mode 100644 doc/bsp_howto/bspstruct.t create mode 100644 doc/bsp_howto/clock.t create mode 100644 doc/bsp_howto/console.t create mode 100644 doc/bsp_howto/init.t create mode 100644 doc/bsp_howto/intro.t create mode 100644 doc/bsp_howto/linkcmds.t create mode 100644 doc/bsp_howto/makefiles.t create mode 100644 doc/bsp_howto/target.t create mode 100644 doc/bsp_howto/timer.t (limited to 'doc/bsp_howto') diff --git a/doc/bsp_howto/Makefile b/doc/bsp_howto/Makefile index 39b0b0d1f6..d258548d73 100644 --- a/doc/bsp_howto/Makefile +++ b/doc/bsp_howto/Makefile @@ -6,7 +6,7 @@ # $Id$ # -PROJECT=started +PROJECT=bsp_howto DISTRIBUTION_LEVEL=public include ../Make.config @@ -18,8 +18,8 @@ dirs: COMMON_FILES=../common/cpright.texi ../common/setup.texi -GENERATED_FILES= buildc.texi buildrt.texi gdb.texi intro.texi \ - nt.texi require.texi sample.texi +GENERATED_FILES= clock.texi console.texi init.texi intro.texi \ + linkcmds.texi bspstruct.texi makefiles.texi target.texi timer.texi FILES= $(PROJECT).texi versions.texi $(GENERATED_FILES) @@ -44,45 +44,53 @@ $(PROJECT).dvi: $(FILES) $(TEXI2DVI) -v $(PROJECT).texi texi2dvi -v $(PROJECT).texi -intro.texi: intro.t versions.texi - $(BMENU) -c -p "Top" \ +intro.texi: intro.t Makefile + $(BMENU) -c -p "" \ -u "Top" \ - -n "Requirements" ${*}.t + -n "" ${*}.t + +target.texi: target.t Makefile + $(BMENU) -c -p "" \ + -u "Top" \ + -n "" ${*}.t + +bspstruct.texi: bspstruct.t Makefile + $(BMENU) -c -p "" \ + -u "Top" \ + -n "" ${*}.t -require.texi: require.t versions.texi - $(BMENU) -c -p "EGCS Mailing List" \ +makefiles.texi: makefiles.t Makefile + $(BMENU) -c -p "" \ -u "Top" \ - -n "Building the GNU C/C++ Cross Compiler Toolset" ${*}.t + -n "" ${*}.t -buildc.texi: buildc.t versions.texi - $(BMENU) -c -p "Requirements" \ +linkcmds.texi: linkcmds.t Makefile + $(BMENU) -c -p "" \ -u "Top" \ - -n "Building RTEMS" ${*}.t + -n "" ${*}.t -buildrt.texi: buildrt.t versions.texi - $(BMENU) -c -p "Running the bit Script" \ +init.texi: init.t Makefile + $(BMENU) -c -p "" \ -u "Top" \ - -n "Building the Sample Application" ${*}.t + -n "" ${*}.t -sample.texi: sample.t versions.texi - $(BMENU) -c -p "Generate RTEMS for a Specific Target and BSP" \ +clock.texi: clock.t Makefile + $(BMENU) -c -p "" \ -u "Top" \ - -n "Building the GNU Debugger" ${*}.t + -n "" ${*}.t -gdb.texi: gdb.t versions.texi - $(BMENU) -c -p "Application Executable" \ +console.texi: console.t Makefile + $(BMENU) -c -p "" \ -u "Top" \ - -n "Using MS-Windows as a Development Host" ${*}.t + -n "" ${*}.t -nt.texi: nt.t versions.texi - $(BMENU) -c -p "GDB for DINK32" \ +timer.texi: timer.t Makefile + $(BMENU) -c -p "" \ -u "Top" \ -n "" ${*}.t html: dirs $(FILES) -mkdir -p $(WWW_INSTALL)/$(PROJECT) - -cp pictures/sfile12c.jpg $(WWW_INSTALL)/$(PROJECT) - -cp pictures/bit_c.jpg $(WWW_INSTALL)/$(PROJECT) $(TEXI2WWW) $(TEXI2WWW_ARGS) -dir $(WWW_INSTALL)/$(PROJECT) \ $(PROJECT).texi diff --git a/doc/bsp_howto/bspstruct.t b/doc/bsp_howto/bspstruct.t new file mode 100644 index 0000000000..cd42da28e3 --- /dev/null +++ b/doc/bsp_howto/bspstruct.t @@ -0,0 +1,37 @@ +@chapter = The Board Support Package Structure + +The BSP are all 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: + +@itemize @bullet + +@item clock : support for the realtime clock, which provides a regular +time basis to the kernel, + +@item console : rather the serial driver than only a console driver, it +deals with the board UARTs (i.e. serial devices), + +@item include : the include files, + +@item startup : the board initialization code, + +@item timer : support of timer devices, + +@item shmsupp : support of shared memory in a multiprocessor system, + +@item network : the KA9Q ethernet driver. + +@end itemize + +Another important element are the makefiles, which have to be provided by +the user. + + +Rem : You should have a copy of the gen68340 BSP +($RTEMS_ROOT/c/src/lib/libbsp/m68k/gen68340) in hand while reading this +piece of documentation. + +Further in this document we'll use the $BSP340_ROOT label for +$RTEMS_ROOT/c/src/lib/libbsp/m68k/gen68340. + diff --git a/doc/bsp_howto/clock.t b/doc/bsp_howto/clock.t new file mode 100644 index 0000000000..403192fd32 --- /dev/null +++ b/doc/bsp_howto/clock.t @@ -0,0 +1,38 @@ +@chapter = The Clock Driver + +@subsection = Introduction + +The clock driver aims at giving a steady time basis to the kernel, so that +the RTEMS primitives that need a clock tick work properly. + +The clock driver is located in the clock directory of the BSP. + +@subsection = Primitives + +@subsection = Initialization + +The major and minor numbers of the clock driver can be made available to +the others, such as the Shared Memory Driver. + +Then you have to program your integrated processor periodic interval timer +so that an interrupt is generated every m microseconds, where m = +BSP_Configuration.microseconds_per_tick. Sometimes the periodic interval +timer can use a prescaler so you have to look carefully at your user's +manual to determine the correct value. + +You must use the RTEMS primitive to put your clock interrupt routine in +the VBR: + +@example +rtems_interrupt_catch (InterruptHandler, CONSOLE_VECTOR, &old_handler); +@end example + +@subsection = The clock interrupt subroutine + +It only has to inform the kernel that a ticker has elapsed, so call : + +@example +rtems_clock_tick(); +@end example + diff --git a/doc/bsp_howto/console.t b/doc/bsp_howto/console.t new file mode 100644 index 0000000000..9aa3132bc3 --- /dev/null +++ b/doc/bsp_howto/console.t @@ -0,0 +1,266 @@ +@chapter = The Console Driver + +@subsection = Introduction + +This chapter describes how to do a console driver using RTEMS Termios +support. + +The serial driver is called as soon as printf/scanf or read/write kind of +input/output are needed. There are two main functioning modes: + +@itemize @bullet + +@item console: formatted input/output, with special characters (end of +line, tabulations, etc...) recognition and processing, + +@item raw: permits raw data processing. + +@end itemize + +We may think that one need two serial drivers to deal with those two types +of data, but Termios permits having only one driver. + +@subsection = Termios + +Termios is a standard for terminal management, included in several Unix +versions. Termios is good because: + +@itemize @bullet + +@item from the user's side: primitives to access the terminal and change +configuration settings are the same under Unix and Rtems. + +@item from the BSP developer's side: it frees you from dealing with buffer +states and mutual exclusions on them. + +@end itemize + +Termios support includes: + +@itemize @bullet + +@item raw and console handling, + +@item blocking or non-blocking characters receive, with or without +Timeout. + +@end itemize + +For more information on Termios, type man termios in your Unix box or go +to http://www.freebsd.org/cgi/man.cgi. + +@subsection = Driver Functioning Modes + +There are generally two main functioning modes for an UART (Universal +Asynchronous Receiver-Transmitter, i.e. the serial chip): + +@itemize @bullet + +@item polling mode: the processor blocks on sending/receiving characters. +This mode is not powerful, but is necessary when one wants to print an +error message when the board hung. This is also the most simple mode to +program, + +@item interrupt mode: the processor doesn't block on sending/receiving +characters. Two buffers (one for the in-going characters, the others for +the characters to be sent) are used. An interrupt is raised as soon as a +character is in the UART. Then the int errupt subroutine insert the +character at the input buffer queue. When a character is asked for input, +this at the head of the buffer is returned. When characters have to be +sent, one have to put the first characters (the number depends on the +UART) in th e UART. Then an interrupt is raised when all the characters +have been emitted. The interrupt subroutine has to send the characters +remaining in the output buffer the same way. + +@end itemize + +@subsection = Serial Driver Functioning Overview + +Figure 5 is an attempt of showing how a Termios driven serial driver works : + +@itemize @bullet + +@item the application programmer uses standard C library call (printf, +scanf, read, write, etc.), + +@item C library (in fact that's Cygnus Newlib) calls RTEMS procedure: glue +is made in newlib*.c files which can be found under +$RTEMS_ROOT/c/src/lib/libc directory, + +@item Glue code calls your serial driver entry routines. + +@end itemize + +@subsection = Polled I/O + +You have to point Termios out which functions are used for simple +character input/output: + + +Function + +Description + +@example +int pollWrite (int minor, const char *buf, int len) + +for (i=0; i. + +@subsection = RTEMS initialization procedure + +The RTEMS initialization procedure is described in the 3rd chapter of the +C user's manual . Please read it carefully. + +There are a few BSP specific functions called from the initialization +manager. They can be found in the startup directory of the BSP. + + + +File + +Function + +Note + +bspstart.c + + + +It starts the application. It includes application, board, and monitor +specific initialization and configuration. + +bspstart.c + +bsp_pretasking_hook + +It starts libc support (needed to allocate some memory using C primitive +malloc for example). Heap size must be passed in argument, this is the one +which is defined in the linkcmds (cf. 5.) + +bspstart.c + +bsp_start + +Here the user and application specific configuration table has been +"loaded" so that BSP_Configuration is up to date. + +You can make last modifications here, for instance reserve more room for +the RTEMS Work Space, or adjust the heap size (you can for example use the +memory left for the lone heap). + +bspclean.c + +bsp_cleanup + +Return control to the monitor. + +@subsection = Drivers initialization + +The Driver Address Table is part of the RTEMS configuration table. It +defines RTEMS drivers entry points (initialization, open, close, read, +write, and control). For more information about this table, check C User's +manual chapter 21 section 6 . + +The RTEMS initialization procedure calls the initialization function for +every driver defined in the RTEMS Configuration Table (this permits to add +only the drivers needed by the application). + +All these primitives have a major and a minor number as arguments: + +@itemize @bullet + +@item the major number refers to the driver type, + +@item the minor number is used to control two peripherals with the same +driver (for instance, we define only one major number for the serial +driver, but two minor numbers for channel A and B if there are two +channels in the UART). + +@end itemize + diff --git a/doc/bsp_howto/intro.t b/doc/bsp_howto/intro.t new file mode 100644 index 0000000000..8cbcdd63a1 --- /dev/null +++ b/doc/bsp_howto/intro.t @@ -0,0 +1,24 @@ +@chapter = Introduction + +Before reading this documentation, it is strongly advised to read the +RTEMS Development Environment Guide to get acquainted with the RTEMS +directory structure. This document describes how to do a RTEMS Board +Support Package, i.e. how to port RTEMS on a new target board. Discussions +are provided for the following topics: + +@itemize @bullet + +@item RTEMS Board Support Packages organization, + +@item Makefiles and the linker command script, + +@item Board initialization code, + +@item Clock driver, + +@item Console driver, + +@item Timer driver. + +@end itemize + diff --git a/doc/bsp_howto/linkcmds.t b/doc/bsp_howto/linkcmds.t new file mode 100644 index 0000000000..62fe323b80 --- /dev/null +++ b/doc/bsp_howto/linkcmds.t @@ -0,0 +1,344 @@ +@chapter = The Linkcmds + +@subsection = What is a "linkcmds" file? + +The linkcmds file is a script which is passed to the linker at linking +time. It holds somewhat the board memory configuration. + +@subsection = Image of an Executable + +A program destined to be embedded has some specificities. Embedded +machines often mean average performances and small memory usage. + +Two types of memories have to be distinguished: one is volatile but on +read and write access (RAM), while the other is non-volatile but read only +(ROM). Even though RAM and ROM can be found in every personal computer, +one generally doesn't care about them , because a program is always put in +RAM and is executed in RAM. That's a bit different in embedded +development: the target will execute the program each time it's reboot or +switched on, which means the program is stored in ROM. On the other hand, +data pr ocessing occurs in RAM. + + + +That leads us to the structure of an embedded program: it's roughly made +of sections, for instance for the Motorola 68k family of microprocessors : + +@itemize @bullet + +@item the code section (aka ".txt" section): it holds the program's main +code, so that it doesn't have to be modified. It's placed in ROM. + +@item the non-initialized data section (aka ".bss" section): it holds non +initialized variables of the program. It can stay in RAM. + +@item the initialized data section (aka ".data" section): it holds the +program data which are to be modified during the program's life, which +means they have to be in RAM. On another hand, these variables must be set +to predefined values, which have to be + stored in ROM... + +@end itemize + +That brings us up to the notion of the image of an executable: it consists +in the set of the program sections. + + + +As a program executable has many sections (note that the user can define +his own, and that compilers define theirs without any notice), one has to +state in which type of memory (RAM or ROM) the sections will be arranged. +For instance, a program compiled f or a Personal Computer will see all the +sections to go to RAM, while a program destined to be embedded will see +some of his sections going into the ROM. + + + +The (section, area of memory) connection is made at linking time. One have +to make the linker know the different sections location once they're in +memory. + + +Figure 2 : sections location in memory + +The GNU linker has a command language to specify the image format. Let's +have a look to the "gen68340" BSP linkcmds, which can be found at +$BSP340_ROOT/startup/linkcmds. + + +@example +OUTPUT_FORMAT(coff-m68k) + +RamSize = DEFINED(RamSize) ? RamSize : 4M; +HeapSize = DEFINED(HeapSize) ? HeapSize : 0x10000; +StackSize = DEFINED(StackSize) ? StackSize : 0x1000; + +MEMORY { + ram : ORIGIN = 0x10000000, LENGTH = 4M + rom : ORIGIN = 0x01000000, LENGTH = 4M +} + +ETHERNET_ADDRESS = DEFINED(ETHERNET_ADDRESS) ? ETHERNET_ADDRESS : 0xDEAD12; + +/* + * Load objects + */ +SECTIONS { + /* + * Hardware variations + */ + _RamSize = RamSize; + __RamSize = RamSize; + + /* + * Boot PROM + */ + rom : { + _RomBase = .; + __RomBase = .; + } >rom + + /* + * Dynamic RAM + */ + ram : { + _RamBase = .; + __RamBase = .; + } >ram + + /* + * Text, data and bss segments + */ + .text : { + CREATE_OBJECT_SYMBOLS + + + *(.text) + + + . = ALIGN (16); + + + /* + * C++ constructors + */ + __CTOR_LIST__ = .; + [......] + __DTOR_END__ = .; + + etext = .; + _etext = .; + } >rom + + .eh_fram : { + . = ALIGN (16); + *(.eh_fram) + } >ram + + .gcc_exc : { + . = ALIGN (16); + *(.gcc_exc) + } >ram + + dpram : { + m340 = .; + _m340 = .; + . += (8 * 1024); + } >ram + + .data : { + copy_start = .; + *(.data) + + . = ALIGN (16); + _edata = .; + copy_end = .; + } >ram + + .bss : { + M68Kvec = .; + _M68Kvec = .; + . += (256 * 4); + + + clear_start = .; + + *(.bss) + + *(COMMON) + + . = ALIGN (16); + _end = .; + + _HeapStart = .; + __HeapStart = .; + . += HeapSize; + . += StackSize; + . = ALIGN (16); + stack_init = .; + + clear_end = .; + + _WorkspaceBase = .; + __WorkspaceBase = .; + + + + } >ram +} +@end example + +executable format is COFF + +your default board RAM size here. + +Note that it's possible to change it by passing an argument to ld + +the default heap size: beware! the heap must be large enough to contain: + +@itemize @bullet + +@item your program's static allocations + +@item your program's dynamic allocations + +@item ALL YOUR PROCESS'S STACK + +@end itemize + +Having a tight heap size is somewhat difficult and many tries are needed +if you want to save the memory usage. + + +The Stacksize should only be large enough to hold the stack in the +initialization sequence. Then the tasks stacks will be allocated in the +Heap. + +Start address of RAM and its length. + +The start address must be a valid address. Most often RAM is assigned to a +given chip of memory on the board, and a Chip Select is assigned to this +chip with an address (see the Initialization sequence chapter). + + +Start address of ROM and its length. Same remarks as above. + +this is for the network driver (see KA9Q documentation for more details) + +define where the sections should go: + +define some variables that the user code can access. + +set the RomBase variable to the start of the ROM. + +set the RamBase variable to the start of the RAM. + +states that a symbol shall be created for each object (.o) + +insert the .text sections of every object + +go to a frontier of 16 bytes (just keep it as is) + +reserve some place for C++ constructors and destructors. + +just keep it as is (or see CROSSGCC mailing-list FAQ for more details) + +declares where the .txt section ends. + +the .txt section goes in ROM! + +this section is created by GCC + +put it in RAM. + +this section is created by GCC + +put it in RAM + +room for peripherals + +needs 8 Kbytes +put it in RAM + +the initialized data section + +put all the objects' .data sections in the .data section of the image + +.data section goes in RAM + +the non initialized data section + + +reserve some room for the Table of Vector Interrupts (256 vectors of 4 bytes) + +pointer to the start of the non initialized data + +put all the objects .bss sections in the .bss section of the image + +put all the non initialized data, which are not in .bss sections + +Heap start + +reserve some room for the heap + +reserve some room for the stack + +top of the stack (remember the stack grows with addresses going down) + +end of the non initialized data + +start of the RTEMS Workspace (holds RTEMS configuration table and a few +other things, its size is calculated by RTEMS according to your +configuration, ) + +the resulting .bss section goes in RAM + + +Now there's a problem with the initialized data: the .data section has to +be in RAM as these data are to be modified during the program execution. +But how will they be initialized at boot time? + + + +One should be aware of the running executable image and the file to +download to the target image being different! In practice, the initialized +data section is copied at the end of the code section (i.e. in ROM) when +building a PROM image. The GNU tool obj copy can be used for this purpose. + + + +Figure 3 : copy of the initialized data section to build a PROM image + + + +This process is made after the linking time, and you can find an example +of how it is done in $RTEMS_ROOT/make/custom/gen68340.cfg : + +@example +# make a prom image +m68k-rtems-objcopy \ +--adjust-section-vma .data= \ + +`m68k-rtems-objdump --section-headers \ +$(basename $@).exe \ +| awk '[...]` \ +$(basename $@).exe +@end example + +use the target objcopy + +we want to move the start of the section .data + +in the resulting image + +the address is given by extracting the address of the end of the .text +section (i.e. in ROM) with an awk script (don't care about it) + +process the image which have just been linked + + + +The board initialization code (cf. 6) will copy the initialized data +initial values (which are stored in ROM) to their reserved location in +RAM. + diff --git a/doc/bsp_howto/makefiles.t b/doc/bsp_howto/makefiles.t new file mode 100644 index 0000000000..db714b9a04 --- /dev/null +++ b/doc/bsp_howto/makefiles.t @@ -0,0 +1,142 @@ +@chapter = The Makefiles + +@subsection = Makefiles Used During The BSP Building Process + +There's a makefile template in each directory of a BSP. They are called +"makefile.in" and are processed when building RTEMS for a given BSP. One +should specify the needed files and directories before the building +process. + +@itemize @bullet + +@item the makefile.in at the BSP root specifies which folders have to be +included. For instance, + +@item We only build the ka9q device driver if HAS_KA9Q was defined + +@example +KA9Q_DRIVER_yes_V = network +KA9Q_DRIVER = $(KA9Q_DRIVER_$(HAS_KA9Q)_V) + +[...] + +SUB_DIRS=include start340 startup clock console timer $(KA9Q_DRIVER) wrapup +@end example + +states that all the directories have to be processed, except for the +network directory which is included only if the user asked for it when +building RTEMS. + +@item the makefile.in in each driver directory. It lists the files to be +included in the driver, so don't forget to add the reference to a new file +in the makefile.in of a given driver when it is created! + +@end itemize + + +Rem : the makefile.in files are ONLY processed during the configure +process of a RTEMS build. It means that, when you're working on the design +of your BSP, and that you're adding a file to a folder and to the +corresponding makefile.in, it will not be take n into account! You have to +run configure again or modify the makefile (result of the makefile.in +process, usually in your /c/src/lib/libbsp/// +directory) by hand. + +@subsection = Makefiles Used Both During The BSP Design and its Use + +A BSP must go with his configuration file. The configuration files can be +found under $RTEMS_ROOT/c/make/custom. The configuration file is taken +into account when building one's application using the template makefiles +($RTEMS_ROOT/c/make/templates), whic h is strongly advised. There are +templates for calling recursively the makefiles in the directories beneath +the current one, building a library or an executable. + +Let's see what it looks like : + +@example +RTEMS_CPU=m68k + +TARGET_ARCH=o-gen68340 +RTEMS_CPU_MODEL=mcpu32 + +include $(RTEMS_ROOT)/make/custom/default.cfg + +RTEMS_BSP_FAMILY=gen68340 + +## Target compiler config file, if any +CONFIG.$(TARGET_ARCH).CC = $(RTEMS_ROOT)/make/compilers/gcc-target-default.cfg + +RTEMS_BSP=gen68340 + +CPU_CFLAGS = -mcpu32 + +# optimize flag: +CFLAGS_OPTIMIZE_V=-O4 -fomit-frame-pointer + +# Override default start file +START_BASE=start340 + +[...] + +ifeq ($(RTEMS_USE_GCC272),yes) +[...] +else + +define make-exe + $(CC) $(CFLAGS) $(CFLAGS_LD) -o $(basename $@).exe $(LINK_OBJS) + $(NM) -g -n $(basename $@).exe > $(basename $@).num + $(SIZE) $(basename $@).exe +endif +@end example + +the main board CPU family + +directory where you want the objects to go + +the main board CPU name for GCC + +include standard definitions + +bsp directory used during the build process + +cross-compiler options + + + + +the name of your bsp directory + +CPU flag to pass to GCC + +optimisation flag to pass to GCC + + +name of your BSP function to be called immediately after reboot + + + +if an older version of GCC is used... + + + +this macro is used in template makefiles to build the final executable. +Any other commands to follow, just as using objcopy to build a PROM image +or converting the executable to binary. + +Figure 1 : custom file for gen68340 BSP ($RTEMS_ROOT/make/custom/gen68340.cfg) + + + +What you have to do: + +@itemize @bullet + +@item copy any .cfg file to .cfg + +@item modify RTEMS_CPU, TARGET_ARCH, RTEMS_CPU_MODEL, RTEMS_BSP_FAMILY, +RTEMS_BSP, CPU_CFLAGS, START_BASE accordingly. + +@end itemize + + diff --git a/doc/bsp_howto/target.t b/doc/bsp_howto/target.t new file mode 100644 index 0000000000..5248390cf0 --- /dev/null +++ b/doc/bsp_howto/target.t @@ -0,0 +1,34 @@ +@chapter = Target Dependent and Board Dependent Files + +RTEMS divides board dependencies into two parts : + +@itemize @bullet + +@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. + +@item the board dependant code : it includes support for a given board, +such as the board initialization code and drivers for the various devices: +clock, UARTs, ethernet board, etc. + + +@end itemize + +Porting RTEMS on a new board should raise two questions : + +@itemize @bullet + +@item is the main board CPU supported ? + +@item does a BSP for a similar board exists ? + +@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. + diff --git a/doc/bsp_howto/timer.t b/doc/bsp_howto/timer.t new file mode 100644 index 0000000000..f8f96b17c2 --- /dev/null +++ b/doc/bsp_howto/timer.t @@ -0,0 +1,66 @@ +@chapter = Timer Driver + +You can program the timer driver for your own needs, but here are two uses +of it: + +@subsection = UART'S FIFO Full Mode + +The gen68340 BSP is an example of the use of the timer to support the UART +input FIFO full mode (FIFO means First In First Out and roughly means +buffer). This mode consists in the UART raising an interrupt when n +characters have been received (n is the UA RT's FIFO length). It results +in a lower interrupt processing time, but the problem is that a scanf +primitive will block on a receipt of less than n characters. The solution +is to set a timer that will check whether there are some characters +waiting in th e UART's input FIFO. The delay time has to be set carefully +otherwise high rates will be broken: + +@itemize @bullet + +@item if no character was received last time the interrupt subroutine was +entered, set a long delay, + +@item otherwise set the delay to the delay needed for n characters +receipt. + +@end itemize + +@subsection = Measuring RTEMS Primitives Time + +RTEMS Timing Test Suite needs a timer support. You have to provide two +primitives: + + + +Function + +Description + +@example +void Timer_initialize (void) +@end example + +Initialize the timer to be a counter to the microsecond. + +@example +int Read_timer (void) +@end example + +Returns the number of microseconds elapsed since the last call to +Timer_initialize. + +@example +rtems_status_code Empty_function (void) + +return RTEMS_SUCCESSFUL; +@end example + +@example +void Set_find_average_overhead (rtems_boolean find_flag) +@end example + +DOES NOTHING ???????????????????????????????????????????????????????????????????????????????????????????????????? + + + + -- cgit v1.2.3