hal-calling-if.html

ecos 很好的源代码

><P
>Diagnostic output appears via the debugging channel as
     initiated by the ROM monitor, allowing for correct behavior
     whether the application was launched via serial or Ethernet, from
     the RedBoot command line or from a debugger.</P
></LI
><LI
><P
> For debugging with raw diagnostic output, mangling is
     disabled.</P
><P
> Debugging session continues as initiated by the ROM monitor,
     whether the application was launched via serial or
     Ethernet. Diagnostic output is directed at the IO port configured
     in the application configuration.</P
><DIV
CLASS="NOTE"
><BLOCKQUOTE
CLASS="NOTE"
><P
><B
>Note:: </B
> There is one caveat to be aware of. If the
       application uses proper devices (be it serial or Ethernet) on
       the same ports as those used by the ROM monitor, the
       connections initiated by the ROM monitor will be
       terminated.</P
></BLOCKQUOTE
></DIV
></LI
></UL
><P
>And for ROM startup configurations:</P
><P
></P
><UL
><LI
><P
> Production configuration with raw output and no debugging
     features (configured for RAM or ROM), mangling is disabled, no
     stubs are included.</P
><P
>Diagnostic output appears (in unmangled form) on the specified
     IO port.</P
></LI
><LI
><P
> RedBoot configuration, includes debugging features and necessary
     mangling.</P
><P
>Diagnostic and debugging output port is auto-selected by the
     first connection to any of the supported IO ports. Can change
     from interactive mode to debugging mode when a debugger is
     detected - when this happens a mangler will be installed as
     required.</P
></LI
><LI
><P
> GDB stubs configuration (obsoleted by RedBoot configuration),
     includes debugging features, mangling is hardwired to GDB
     protocol.</P
><P
>Diagnostic and debugging output is hardwired to configured IO
     ports, mangling is hardwired.</P
></LI
></UL
></DIV
><DIV
CLASS="SECTION"
><H3
CLASS="SECTION"
><A
NAME="AEN9086">Footnote: Design Reasoning for Control of Console Channel</H3
><P
>The current code for controlling the console channel is a
replacement for an older implementation which had some shortcomings
which addressed by the new implementation.</P
><P
>This is what the old implementation did: on initialization it would
check if the CDL configured console channel differed from the active
debug channel - and if so, set the console channel, thereby disabling
mangling.</P
><P
>The idea was that whatever channel was configured to be used for
console (i.e., diagnostic output) in the application was what should
be used. Also, it meant that if debug and console channels were
normally the same, a changed console channel would imply a request for
unmangled output.</P
><P
>But this prevented at least two things:</P
><P
></P
><UL
><LI
><P
> It was impossible to inherit the existing connection by which
     the application was launched (either by RedBoot commands via
     telnet, or by via a debugger).</P
><P
>This was mostly a problem on targets supporting Ethernet
     access since the diagnostic output would not be returned via the
     Ethernet connection, but on the configured serial port.</P
><P
>The problem also occurred on any targets with multiple serial
     ports where the ROM monitor was configured to use a different
     port than the CDL defaults.</P
></LI
><LI
><P
> Proper control of when to mangle or just write out raw ASCII
        text.</P
><P
>Sometimes it's desirable to disable mangling, even if the
     channel specified is the same as that used for debugging. This
     usually happens if GDB is used to download the application, but
     direct interaction with the application on the same channel is
     desired (GDB protocol only allows output from the target, no
     input).</P
></LI
></UL
></DIV
></DIV
><DIV
CLASS="SECTION"
><H2
CLASS="SECTION"
><A
NAME="AEN9100">The calling Interface API</H2
><P
>The calling interface API is defined by hal_if.h and hal_if.c in
hal/common.</P
><P
>The API provides a set of services. Different platforms, or
different versions of the ROM monitor for a single platform, may
implement fewer or extra service. The table has room for growth, and
any entries which are not supported map to a NOP-service (when called
it returns 0 (<TT
CLASS="LITERAL"
>false</TT
>)).</P
><P
>A client of a service should either be selected by configuration,
or have suitable fall back alternatives in case the feature is not
implemented by the ROM monitor.</P
><DIV
CLASS="NOTE"
><BLOCKQUOTE
CLASS="NOTE"
><P
><B
>Note:: </B
>Checking for unimplemented service when this may be a data
field/pointer instead of a function: suggest reserving the last entry
in the table as the NOP-service pointer. Then clients can compare a
service entry with this pointer to determine whether it's initialized
or not.</P
></BLOCKQUOTE
></DIV
><P
>The header file <TT
CLASS="FILENAME"
>cyg/hal/hal_if.h</TT
> defines
 the table layout and accessor macros (allowing primitive type
 checking and alternative implementations should it become necessary).</P
><P
>The source file <TT
CLASS="FILENAME"
>hal_if.c</TT
> defines the table
 initialization function. All HALs should call this during platform
 initialization - the table will get initialized according to
 configuration.  Also defined here are wrapper functions which map
 between the calling interface API and the API of the used eCos
 functions.</P
><DIV
CLASS="SECTION"
><H3
CLASS="SECTION"
><A
NAME="AEN9113">Implemented Services</H3
><P
>This is a brief description of the services, some of which are
described in further detail below.</P
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
><TT
CLASS="LITERAL"
>VERSION</TT
></DT
><DD
><P
>Version of table. Serves as a way to check for how many
        features are available in the table. This is the index of the
        last service in the table.</P
></DD
><DT
><TT
CLASS="LITERAL"
>KILL_VECTOR</TT
></DT
><DD
><P
>[Presently unused by the stub code, but initialized] This
        vector defines a function to execute when the system receives
        a kill signal from the debugger. It is initialized with the
        reset function (see below), but the application (or eCos) can
        override it if necessary.</P
></DD
><DT
><TT
CLASS="LITERAL"
>CONSOLE_PROCS</TT
></DT
><DD
><P
>The communication procedure table used for console IO
        (see <A
HREF="hal-calling-if.html#HAL-PORTING-IO-CHANNELS"
>the Section called <I
>IO channels</I
></A
>.</P
></DD
><DT
><TT
CLASS="LITERAL"
>DEBUG_PROCS</TT
></DT
><DD
><P
>The communication procedure table used for debugger IO
        (see <A
HREF="hal-calling-if.html#HAL-PORTING-IO-CHANNELS"
>the Section called <I
>IO channels</I
></A
>).</P
></DD
><DT
><TT
CLASS="LITERAL"
>FLUSH_DCACHE</TT
></DT
><DD
><P
>Flushes the data cache for the specified
        region. Some implementations may flush the entire data cache.</P
></DD
><DT
><TT
CLASS="LITERAL"
>FLUSH_ICACHE</TT
></DT
><DD
><P
>Flushes (invalidates) the instruction cache
        for the specified region. Some implementations may flush the
        entire instruction cache.</P
></DD
><DT
><TT
CLASS="LITERAL"
>SET_DEBUG_COMM</TT
></DT
><DD
><P
>Change debugging communication channel.</P
></DD
><DT
><TT
CLASS="LITERAL"
>SET_CONSOLE_COMM</TT
></DT
><DD
><P
>Change console communication channel.</P
></DD
><DT
><TT
CLASS="LITERAL"
>DBG_SYSCALL</TT
></DT
><DD
><P
>Vector used to communication between debugger functions in
        ROM and in RAM. RAM eCos configurations may install a function
        pointer here which the ROM monitor uses to get thread
        information from the kernel running in RAM.</P
></DD
><DT
><TT
CLASS="LITERAL"
>RESET</TT
></DT
><DD
><P
>Resets the board on call. If it is not possible to reset
        the board from software, it will jump to the ROM entry point
        which will perform a "software" reset of the board.</P
></DD
><DT
><TT
CLASS="LITERAL"
>CONSOLE_INTERRUPT_FLAG</TT
></DT
><DD
><P
>Set if a debugger interrupt request was detected while
        processing console IO. Allows the actual breakpoint action to
        be handled after return to RAM, ensuring proper backtraces
        etc.</P
></DD
><DT
><TT
CLASS="LITERAL"
>DELAY_US</TT
></DT
><DD
><P
>Will delay the specified number of microseconds. The
        precision is platform dependent to some extend - a small value
        (&#60;100us) is likely to cause bigger delays than requested.</P
></DD
><DT
><TT
CLASS="LITERAL"
>FLASH_CFG_OP</TT
></DT
><DD
><P
>For accessing configuration settings kept in flash memory.</P
></DD
><DT
><TT
CLASS="LITERAL"
>INSTALL_BPT_FN</TT
></DT
><DD
><P
>Installs a breakpoint at the specified address. This is
        used by the asynchronous breakpoint support
	(see ).</P
></DD
></DL
></DIV
></DIV
><DIV
CLASS="SECTION"
><H3
CLASS="SECTION"
><A
NAME="AEN9189">Compatibility</H3
><P
>When a platform is changed to support the calling interface,
applications will use it if so configured. That means that if an
application is run on a platform with an older ROM monitor, the
service is almost guaranteed to fail.</P
><P
>For this reason, applications should only use Console Comm for HAL
diagnostics output if explicitly configured to do so
(<TT
CLASS="LITERAL"
>CYGSEM_HAL_VIRTUAL_VECTOR_DIAG</TT
>).</P
><P
>As for asynchronous GDB interrupts, the service will always be
used. This is likely to cause a crash under older ROM monitors, but
this crash may be caught by the debugger. The old workaround still
applies: if you need asynchronous breakpoints or thread debugging
under older ROM monitors, you may have to include the debugging
support when configuring eCos.</P
></DIV
><DIV
CLASS="SECTION"
><H3
CLASS="SECTION"
><A
NAME="AEN9195">Implementation details</H3
><P
>During the startup of a ROM monitor, the calling table will be
initialized. This also happens if eCos is configured <SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>not</I
></SPAN
> to rely on
a ROM monitor.</P
><DIV
CLASS="NOTE"
><BLOCKQUOTE
CLASS="NOTE"
><P
><B
>Note:: </B
> There is reserved space (256 bytes) for the vector
table whether it gets used or not. This may be something that we want
to change if we ever have to shave off every last byte for a given
target.</P
></BLOCKQUOTE
></DIV
><P
>If thread debugging features are enabled, the function for accessing
the thread information gets registered in the table during startup of
a RAM startup configuration.</P
><P
>Further implementation details are described where the service itself
is described.</P
></DIV
><DIV
CLASS="SECTION"
><H3
CLASS="SECTION"
><A
NAME="AEN9204">New Platform Ports</H3
><P
>The <TT
CLASS="FUNCTION"
>hal_platform_init()</TT
> function must call
<TT
CLASS="FUNCTION"
>hal_if_init()</TT
>.</P
><P
>The HAL serial driver must, when called via
<TT
CLASS="FUNCTION"
>cyg_hal_plf_comms_init()</TT
> must initialize the
communication channels.</P
><P
>The <TT
CLASS="FUNCTION"
>reset()</TT
> function defined in
<TT
CLASS="FILENAME"
>hal_if.c</TT
> will attempt to do a hardware reset, but
if this fails it will fall back to simply jumping to the reset
entry-point. On most platforms the startup initialization will go a
long way to reset the target to a sane state (there will be
exceptions, of course). For this reason, make sure to define
<TT
CLASS="LITERAL"
>HAL_STUB_PLATFORM_RESET_ENTRY</TT
> in plf_stub.h.</P
><P
>All debugging features must be in place in order for the debugging
services to be functional. See general platform porting notes.</P
></DIV
><DIV
CLASS="SECTION"
><H3
CLASS="SECTION"
><A
NAME="AEN9216">New architecture ports</H3
><P
>There are no specific requirements for a new architecture port in
order to support the calling interface, but the basic debugging
features must be in place. See general architecture porting notes.</P
></DIV
></DIV
><DIV
CLASS="SECTION"
><H2
CLASS="SECTION"
><A
NAME="HAL-PORTING-IO-CHANNELS">IO channels</H2
><P
>The calling interface provides procedure tables for all IO channels on
the platform. These are used for console (diagnostic) and debugger IO,