📄 hal-porting-platform.html
字号:
<!-- Copyright (C) 2003 Red Hat, Inc. -->
<!-- This material may be distributed only subject to the terms -->
<!-- and conditions set forth in the Open Publication License, v1.0 -->
<!-- or later (the latest version is presently available at -->
<!-- http://www.opencontent.org/openpub/). -->
<!-- Distribution of the work or derivative of the work in any -->
<!-- standard (paper) book form is prohibited unless prior -->
<!-- permission is obtained from the copyright holder. -->
<HTML
><HEAD
><TITLE
>Platform HAL Porting</TITLE
><meta name="MSSmartTagsPreventParsing" content="TRUE">
<META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
"><LINK
REL="HOME"
TITLE="eCos Reference Manual"
HREF="ecos-ref.html"><LINK
REL="UP"
TITLE=" Porting Guide"
HREF="hal-porting-guide.html"><LINK
REL="PREVIOUS"
TITLE="HAL Coding Conventions"
HREF="hal-porting-coding-conventions.html"><LINK
REL="NEXT"
TITLE="Variant HAL Porting"
HREF="hal-porting-variant.html"></HEAD
><BODY
CLASS="SECTION"
BGCOLOR="#FFFFFF"
TEXT="#000000"
LINK="#0000FF"
VLINK="#840084"
ALINK="#0000FF"
><DIV
CLASS="NAVHEADER"
><TABLE
SUMMARY="Header navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TH
COLSPAN="3"
ALIGN="center"
>eCos Reference Manual</TH
></TR
><TR
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="bottom"
><A
HREF="hal-porting-coding-conventions.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="80%"
ALIGN="center"
VALIGN="bottom"
>Chapter 11. Porting Guide</TD
><TD
WIDTH="10%"
ALIGN="right"
VALIGN="bottom"
><A
HREF="hal-porting-variant.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
></TABLE
><HR
ALIGN="LEFT"
WIDTH="100%"></DIV
><DIV
CLASS="SECTION"
><H1
CLASS="SECTION"
><A
NAME="HAL-PORTING-PLATFORM">Platform HAL Porting</H1
><P
>This is the type of port that takes the least effort. It basically
consists of describing the platform (board) for the HAL: memory
layout, early platform initialization, interrupt controllers, and a
simple serial device driver.</P
><P
>Doing a platform port requires a preexisting architecture and
possibly a variant HAL port.</P
><DIV
CLASS="SECTION"
><H2
CLASS="SECTION"
><A
NAME="AEN9414">HAL Platform Porting Process</H2
><DIV
CLASS="SECTION"
><H3
CLASS="SECTION"
><A
NAME="AEN9416">Brief overview</H3
><P
>The easiest way to make a new platform HAL is simply to copy an
existing platform HAL of the same architecture/variant and change all
the files to match the new one. In case this is the first platform for
the architecture/variant, a platform HAL from another architecture
should be used as a template.</P
><P
>The best way to start a platform port is to concentrate on getting
RedBoot to run. RedBoot is a simpler environment than full eCos, it
does not use interrupts or threads, but covers most of the
basic startup requirements.</P
><P
>RedBoot normally runs out of FLASH or ROM and provides program loading
and debugging facilities. This allows further HAL development to
happen using RAM startup configurations, which is desirable for the
simple reason that downloading an image which you need to test is
often many times faster than either updating a flash part, or indeed,
erasing and reprogramming an EPROM.</P
><P
>There are two approaches to getting to this first goal:</P
><P
></P
><OL
TYPE="1"
><LI
><P
>The board is equipped with a ROM monitor which allows "load and go" of
ELF, binary, S-record or some other image type which can be created
using <SPAN
CLASS="APPLICATION"
>objcopy</SPAN
>. This allows you to develop
RedBoot by downloading and running the code (saving time).</P
><P
>When the stub is running it is a good idea to examine the various
hardware registers to help you write the platform initialization code.</P
><P
>Then you may have to fiddle a bit going through step two (getting it
to run from ROM startup). If at all possible, preserve the original
ROM monitor so you can revert to it if necessary.</P
></LI
><LI
><P
>The board has no ROM monitor. You need to get the platform
initialization and stub working by repeatedly making changes, updating
flash or EPROM and testing the changes. If you are lucky, you have a
JTAG or similar CPU debugger to help you. If not, you will probably
learn to appreciate LEDs. This approach may also be needed during the
initial phase of moving RedBoot from RAM startup to ROM, since it is
very unlikely to work first time.</P
></LI
></OL
></DIV
><DIV
CLASS="SECTION"
><H3
CLASS="SECTION"
><A
NAME="AEN9430">Step-by-step</H3
><P
>Given that no two platforms are exactly the same, you may have to
deviate from the below. Also, you should expect a fair amount of
fiddling - things almost never go right the first time. See the hints
section below for some suggestions that might help debugging.</P
><P
>The description below is based on the HAL layout used in the MIPS,
PC and MN10300 HALs. Eventually all HALs should be converted to look like
these - but in a transition period there will be other HALs which look
substantially different. Please try to adhere to the following as much is
possible without causing yourself too much grief integrating with a
HAL which does not follow this layout.</P
><DIV
CLASS="SECTION"
><H4
CLASS="SECTION"
><A
NAME="AEN9434">Minimal requirements</H4
><P
>These are the changes you must make before you attempt to build
RedBoot. You are advised to read all the sources though.</P
><P
></P
><OL
TYPE="1"
><LI
><P
>Copy an existing platform HAL from the same or another
architecture. Rename the files as necessary to follow the
standard: CDL and MLT related files should contain the
<arch>_<variant>_<platform> triplet.</P
></LI
><LI
><P
>Adjust CDL options. Primarily option naming, real-time
clock/counter, and CYGHWR_MEMORY_LAYOUT variables, but also other
options may need editing. Look through the architecture/variant
CDL files to see if there are any requirements/features which
where not used on the platform you copied. If so, add appropriate
ones. See <A
HREF="hal-porting-platform.html#HAL-PORTING-CDL-REQUIREMENTS"
>the Section called <I
>HAL Platform CDL</I
></A
> for more
details.</P
></LI
><LI
><P
>Add the necessary packages and target descriptions to the
top-level <TT
CLASS="FILENAME"
>ecos.db</TT
> file. See <A
HREF="hal-porting-platform.html#HAL-PORTING-ECOS-DATABASE"
>the Section called <I
>eCos Database</I
></A
>. Initially, the target entry
should only contain the HAL packages. Other hardware support
packages will be added later.</P
></LI
><LI
><P
>Adjust the MLT files in
<TT
CLASS="FILENAME"
>include/pkgconf</TT
> to match the memory layout on
the platform. For initial testing it should be enough to just hand
edit .h and .ldi files, but eventually you should generate all
files using the memory layout editor in the configuration
tool. See <A
HREF="hal-porting-platform.html#HAL-PORTING-PLATFORM-MEMORY-LAYOUT"
>the Section called <I
>Platform Memory Layout</I
></A
> for
more details.</P
></LI
><LI
><P
> Edit the <TT
CLASS="FILENAME"
>misc/redboot_<STARTUP>.ecm</TT
> for
the startup type you have chosen to begin with. Rename any
platform specific options and remove any that do not apply. In the
<TT
CLASS="LITERAL"
>cdl_configuration</TT
> section, comment out any
extra packages that are added, particularly packages such as
<TT
CLASS="LITERAL"
>CYGPKG_IO_FLASH</TT
> and
<TT
CLASS="LITERAL"
>CYGPKG_IO_ETH_DRIVERS</TT
>. These are not needed for
initial porting and will be added back later.
</P
></LI
><LI
><P
>If the default IO macros are not correct, override them in
plf_io.h. This may be necessary if the platform uses a different
endianness from the default for the CPU.</P
></LI
><LI
><P
>Leave out/comment out code that enables caches and/or MMU if
possible. Execution speed will not be a concern until the port is
feature complete.</P
></LI
><LI
><P
>Implement a simple serial driver (polled mode only). Make sure the
initialization function properly hooks the procedures up in the
virtual vector IO channel tables. RedBoot will call the serial
driver via these tables.</P
><P
> By copying an existing platform HAL most of this code will be
already done, and will only need the platform specific hardware
access code to be written.
</P
></LI
><LI
><P
>Adjust/implement necessary platform
initialization. This can be found in
<TT
CLASS="FILENAME"
>platform.inc</TT
> and
<TT
CLASS="FILENAME"
>platform.S</TT
> files (ARM:
<TT
CLASS="FILENAME"
>hal_platform_setup.h</TT
> and
<TT
CLASS="FILENAME"
><platform>_misc.c</TT
>, PowerPC:
<TT
CLASS="FILENAME"
><platform>.S</TT
>). This step can be
postponed if you are doing a RAM startup RedBoot first and the
existing ROM monitor handles board initialization.</P
></LI
><LI
><P
>Define <TT
CLASS="LITERAL"
>HAL_STUB_PLATFORM_RESET</TT
>
(optionally empty) and
<TT
CLASS="LITERAL"
>HAL_STUB_PLATFORM_RESET_ENTRY</TT
> so that RedBoot
can reset-on-detach - this is very handy, often removing the need
for physically resetting the board between downloads.</P
></LI
></OL
><P
>You should now be able to build RedBoot. For ROM startup:</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>% ecosconfig new <target_name> redboot
% ecosconfig import $(ECOS_REPOSITORY)/hal/<architecture>/<platform>/<version>/misc/redboot_ROM.ecm
% ecosconfig tree
% make</PRE
></TD
></TR
></TABLE
><P
>You may have to make further changes than suggested above to get
the make command to succeed. But when it does, you should find a
RedBoot image in install/bin. To program this image into flash or
EPROM, you may need to convert to some other file type, and possibly
adjust the start address. When you have the correct
<SPAN
CLASS="APPLICATION"
>objcopy</SPAN
> command to do this, add it to the
<TT
CLASS="LITERAL"
>CYGBLD_BUILD_GDB_STUBS</TT
> custom build rule in the
platform CDL file.</P
><P
>Having updated the flash/EPROM on the board, you should see output
on the serial port looking like this when powering on the board:</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>RedBoot(tm) bootstrap and debug environment [ROMRAM]
Non-certified release, version UNKNOWN - built 15:42:24, Mar 14 2002
Platform: <PLATFORM> (<ARCHITECTURE> <VARIANT>)
Copyright (C) 2000, 2001, 2002, Red Hat, Inc.
RAM: 0x00000000-0x01000000, 0x000293e8-0x00ed1000 available
FLASH: 0x24000000 - 0x26000000, 256 blocks of 0x00020000 bytes each.
RedBoot> </PRE
></TD
></TR
></TABLE
><P
>If you do not see this output, you need to go through all your
changes and figure out what's wrong. If there's a user programmable
LED or LCD on the board it may help you figure out how far RedBoot
gets before it hangs. Unfortunately there's no good way to describe
what to do in this situation - other than that you have to play with
the code and the board.</P
></DIV
><DIV
CLASS="SECTION"
><H4
CLASS="SECTION"
><A
NAME="AEN9483">Adding features</H4
><P
>Now you should have a basic RedBoot running on the board. This
means you have a the correct board initialization and a working serial
driver. It's time to flesh out the remaining HAL features.</P
><P
></P
><OL
TYPE="1"
><LI
><P
>Reset. As mentioned above it is desirable to get the board to
reset when GDB disconnects. When GDB disconnects it sends RedBoot
a kill-packet, and RedBoot first calls <TT
CLASS="LITERAL"
>HAL_STUB_PLATFORM_RESET()</TT
>,
attempting to perform a software-invoked reset. Most embedded
CPUs/boards have a watchdog which is capable of triggering a reset.
If your target does not have a watchdog, leave
<TT
CLASS="LITERAL"
>HAL_STUB_PLATFORM_RESET()</TT
> empty and rely on the fallback approach.</P
><P
>If <TT
CLASS="LITERAL"
>HAL_STUB_PLATFORM_RESET()</TT
> did not cause a reset, RedBoot will
jump to <TT
CLASS="LITERAL"
>HAL_STUB_PLATFORM_RESET_ENTRY</TT
> - this should be the address
where the CPU will start execution after a reset. Re-initializing the
board and drivers will <SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>usually</I
></SPAN
> be good enough to make a
hardware reset unnecessary.</P
><P
>After the reset caused by the kill-packet, the target will be ready
for GDB to connect again. During a days work, this will save you from
pressing the reset button many times.</P
><P
>Note that it is possible to disconnect from the board without
causing it to reset by using the GDB command "detach".</P
></LI
><LI
><P
>Single-stepping is necessary for both instruction-level debugging
and for breakpoint support. Single-stepping support should already be
in place as part of the architecture/variant HAL, but you want to give
it a quick test since you will come to rely on it.</P
></LI
><LI
><P
>Real-time clock interrupts drive the eCos scheduler clock. Many
embedded CPUs have an on-core timer (e.g. SH) or decrementer
(e.g. MIPS, PPC) that can be used, and in this case it will already be
supported by the architecture/variant HAL. You only have to calculate
and enter the proper <TT
CLASS="LITERAL"
>CYGNUM_HAL_RTC_CONSTANTS</TT
>
definitions in the platform CDL file.</P
><P
>On some targets it may be necessary to use a platform-specific
timer source for driving the real-time clock. In this case you also
have to enter the proper CDL definitions, but must also define
suitable versions of the <TT
CLASS="LITERAL"
>HAL_CLOCK_XXXX</TT
> macros.</P
></LI
><LI
><P
>Interrupt decoding usually differs between platforms because the
number and type of devices on the board differ. In
<TT
CLASS="FILENAME"
>plf_intr.h</TT
> (ARM:
<TT
CLASS="FILENAME"
>hal_platform_ints.h</TT
>) you must either extend or
replace the default vector definitions provided by the architecture
or variant interrupt headers. You may also have to define
<TT
CLASS="LITERAL"
>HAL_INTERRUPT_XXXX</TT
> control macros.</P
></LI
><LI
><P
>Caching may also differ from architecture/variant definitions.
This maybe just the cache sizes, but there can also be bigger
differences for example if the platform supports 2nd level caches.</P
><P
>When cache definitions are in place, enable the caches on
startup. First verify that the system is stable for RAM startups, then
build a new RedBoot and install it. This will test if caching, and in
particular the cache sync/flush operations, also work for ROM startup.</P
></LI
><LI
><P
>Asynchronous breakpoints allow you to stop application execution
and enter the debugger. Asynchronous breakpoint details are described
in .</P
></LI
></OL
><P
>You should now have a completed platform HAL port. Verify its
stability and completeness by running all the eCos tests and fix any
problems that show up (you have a working RedBoot now, remember! That
means you can debug the code to see why it fails).</P
><P
>Given the many configuration options in eCos, there may be hidden
bugs or missing features that do not show up even if you run all the
tests successfully with a default configuration. A comprehensive test
of the entire system will take many configuration permutations and
many many thousands of tests executed.</P
></DIV
></DIV
><DIV
CLASS="SECTION"
><H3
CLASS="SECTION"
><A
NAME="AEN9516">Hints</H3
><P
></P
><UL
><LI
><P
>JTAG or similar CPU debugging hardware can greatly reduce the time
it takes to write a HAL port since you always have full visibility
of what the CPU is doing.
</P
></LI
><LI
><P
>LEDs can be your friends if you don't have a JTAG
device. Especially in the start of the porting effort if you don't
already have a working ROM monitor on the target. Then you have to
get a basic RedBoot working while basically being blindfolded. The
LED can make it little easier, as you'll be able to do limited
tracking of program flow and behavior by switching the LED on and
off. If the board has multiple LEDs you can show a number (using
binary notation with the LEDs) and sprinkle code which sets
different numbers throughout the code.</P
></LI
><LI
><P
⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -