porting.sgml

eCos操作系统源码

 configuration.  Also defined here are wrapper functions which map
 between the calling interface API and the API of the used eCos
 functions.
</para>

<!-- {{{ Implemented Services -->

<section>
<title>Implemented Services</title>

<para>This is a brief description of the services, some of which are
described in further detail below.</para>

<variablelist>
<varlistentry><term><literal>VERSION</literal></term>
        <listitem><para>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.</para></listitem></varlistentry>
<varlistentry><term><literal>KILL_VECTOR</literal></term>
        <listitem><para>[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.</para></listitem></varlistentry>
<varlistentry><term><literal>CONSOLE_PROCS</literal></term>
        <listitem><para>The communication procedure table used for console IO
        (see <xref linkend="hal-porting-io-channels">.</para></listitem></varlistentry>
<varlistentry><term><literal>DEBUG_PROCS</literal></term>
        <listitem><para>The communication procedure table used for debugger IO
        (see <xref linkend="hal-porting-io-channels">).</para></listitem></varlistentry>
<varlistentry><term><literal>FLUSH_DCACHE</literal></term>
        <listitem><para>Flushes the data cache for the specified
        region. Some implementations may flush the entire data cache.</para></listitem></varlistentry>
<varlistentry><term><literal>FLUSH_ICACHE</literal></term>
        <listitem><para>Flushes (invalidates) the instruction cache
        for the specified region. Some implementations may flush the
        entire instruction cache.</para></listitem></varlistentry>
<varlistentry><term><literal>SET_DEBUG_COMM</literal></term>
        <listitem><para>Change debugging communication channel.</para></listitem></varlistentry>
<varlistentry><term><literal>SET_CONSOLE_COMM</literal></term>
        <listitem><para>Change console communication channel.</para></listitem></varlistentry>
<varlistentry><term><literal>DBG_SYSCALL</literal></term>
        <listitem><para>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.</para></listitem></varlistentry>
<varlistentry><term><literal>RESET</literal></term>
        <listitem><para>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.</para></listitem></varlistentry>
<varlistentry><term><literal>CONSOLE_INTERRUPT_FLAG</literal></term>
        <listitem><para>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.</para></listitem></varlistentry>
<varlistentry><term><literal>DELAY_US</literal></term>
        <listitem><para>Will delay the specified number of microseconds. The
        precision is platform dependent to some extend - a small value
        (<100us) is likely to cause bigger delays than requested.</para></listitem></varlistentry>
<varlistentry><term><literal>FLASH_CFG_OP</literal></term>
        <listitem><para>For accessing configuration settings kept in flash memory.</para></listitem></varlistentry>
<varlistentry><term><literal>INSTALL_BPT_FN</literal></term>
        <listitem><para>Installs a breakpoint at the specified address. This is
        used by the asynchronous breakpoint support
	(see <!-- <xref linkend="hal-stubs-async-bps"> -->).</para></listitem></varlistentry>
</variablelist>
</section>

<!-- }}} -->
<!-- {{{ Compatibility -->

<section>
<title>Compatibility</title>

<para>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.
</para>

<para>For this reason, applications should only use Console Comm for HAL
diagnostics output if explicitly configured to do so
(<literal>CYGSEM_HAL_VIRTUAL_VECTOR_DIAG</literal>).
</para>

<para>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.
</para>

</section>

<!-- }}} -->
<!-- {{{ Implementation Details -->

<section>
<title>Implementation details</title>

<para>During the startup of a ROM monitor, the calling table will be
initialized. This also happens if eCos is configured <emphasis>not</emphasis> to rely on
a ROM monitor.
</para>

<note>
<title>Note:</title>
<para> 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.
</para>
</note>

<para>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.
</para>

<para>Further implementation details are described where the service itself
is described.</para>

<!-- 
FIXME: Need to describe the CYGARC_HAL_SAVE_GP() and
CYGARC_HAL_RESTORE_GP() macros.
-->

</section>

<!-- }}} -->
<!-- {{{ New Platform Ports -->

<section>
<title>New Platform Ports</title>

<para>The <function>hal_platform_init()</function> function must call
<function>hal_if_init()</function>.
</para>

<para>The HAL serial driver must, when called via
<function>cyg_hal_plf_comms_init()</function> must initialize the
communication channels.
</para>

<para>The <function>reset()</function> function defined in
<filename>hal_if.c</filename> 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
<literal>HAL_STUB_PLATFORM_RESET_ENTRY</literal> in plf_stub.h.
</para>

<para>All debugging features must be in place in order for the debugging
services to be functional. See general platform porting notes.
</para>

</section>

<!-- }}} -->
<!-- {{{ New Architecture Ports -->

<section>
<title>New architecture ports</title>

<para>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.
</para>
</section>

<!-- }}} -->

</section>

<!-- }}} -->
<!-- {{{ IO Channels -->

<section id="hal-porting-io-channels">
<title>IO channels</title>


<para>The calling interface provides procedure tables for all IO channels on
the platform. These are used for console (diagnostic) and debugger IO,
allowing a ROM monitor to provided all the needed IO routines. At
the same time, this makes it easy to switch console/debugger channels
at run-time (the old implementation had hardwired drivers for console
and debugger IO, preventing these to change at run-time).
</para>

<para>The hal_if provides wrappers which interface these services to the
eCos infrastructure diagnostics routines. This is done in a way which
ensures proper string mangling of the diagnostics output when required
(e.g. O-packetization when using a GDB compatible ROM monitor).
</para>

<!-- {{{ Available Procedures -->

<section>
<title>Available Procedures</title>

<para>This is a brief description of the procedures</para>

<variablelist>
<varlistentry><term><literal>CH_DATA</literal></term>
<listitem><para>Pointer to the controller IO base (or a pointer to a per-device
    structure if more data than the IO base is required). All the
    procedures below are called with this data item as the first
    argument.</para></listitem></varlistentry>

<varlistentry><term><literal>WRITE</literal></term>
        <listitem><para>Writes the buffer to the device.</para></listitem></varlistentry>
<varlistentry><term><literal>READ</literal></term>
        <listitem><para>Fills a buffer from the device.</para></listitem></varlistentry>
<varlistentry><term><literal>PUTC</literal></term>
        <listitem><para>Write a character to the device.</para></listitem></varlistentry>
<varlistentry><term><literal>GETC</literal></term>
        <listitem><para>Read a character from the device.</para></listitem></varlistentry>
<varlistentry><term><literal>CONTROL</literal></term>
        <listitem><para>Device feature control. Second argument specifies function:</para>
  <variablelist>
    <varlistentry><term><literal>SETBAUD</literal></term>
        <listitem><para>Changes baud rate.</para></listitem></varlistentry>
    <varlistentry><term><literal>GETBAUD</literal></term>
        <listitem><para>Returns the current baud rate.</para></listitem></varlistentry>
    <varlistentry><term><literal>INSTALL_DBG_ISR</literal></term>
        <listitem><para>[Unused]</para></listitem></varlistentry>
    <varlistentry><term><literal>REMOVE_DBG_ISR</literal></term>
        <listitem><para>[Unused]</para></listitem></varlistentry>
    <varlistentry><term><literal>IRQ_DISABLE</literal></term>
        <listitem><para>Disable debugging receive interrupts on the device.</para></listitem></varlistentry>
    <varlistentry><term><literal>IRQ_ENABLE</literal></term>
        <listitem><para>Enable debugging receive interrupts on the device.</para></listitem></varlistentry>
    <varlistentry><term><literal>DBG_ISR_VECTOR</literal></term>
        <listitem><para>Returns the ISR vector used by the device for debugging
        receive interrupts.</para></listitem></varlistentry>
    <varlistentry><term><literal>SET_TIMEOUT</literal></term>
        <listitem><para>Set GETC timeout in milliseconds.</para></listitem></varlistentry>
    <varlistentry><term><literal>FLUSH_OUTPUT</literal></term>
        <listitem><para>Forces driver to flush data in its buffers. Note
            that this may not affect hardware buffers
        (e.g. FIFOs).</para></listitem></varlistentry>
   </variablelist>
   </listitem></varlistentry>
   
<varlistentry><term><literal>DBG_ISR</literal></term>
        <listitem><para>ISR used to handle receive interrupts from the
	device (see <!-- <xref linkend="hal-stubs-async-bps"> -->).</para></listitem></varlistentry>
<varlistentry><term><literal>GETC_TIMEOUT</literal></term>
        <listitem><para>Read a character from the device with timeout.</para></listitem></varlistentry>
</variablelist>

</section>

<!-- }}} -->
<!-- {{{ Usage -->

<section><title>Usage</title>

<para>The standard eCos diagnostics IO functions use the channel
procedure table when <literal>CYGSEM_HAL_VIRTUAL_VECTOR_DIAG</literal> is enabled. That
means that when you use diag_printf (or the libc printf function) the
stream goes through the selected console procedure table. If you use
the virtual vector function SET_CONSOLE_COMM you can change the device
which the diagnostics output goes to at run-time.</para>

<para>You can also use the table functions directly if desired
(regardless of the <literal>CYGSEM_HAL_VIRTUAL_VECTOR_DIAG</literal> setting - assuming
the ROM monitor provides the services). Here is a small example which
changes the console to use channel 2, fetches the comm procs pointer
and calls the write function from that table, then restores the
console to the original channel:</para>

<programlisting>
#define T "Hello World!\n"

int
main(void)
{
    hal_virtual_comm_table_t* comm;
    int cur = CYGACC_CALL_IF_SET_CONSOLE_COMM(CYGNUM_CALL_IF_SET_COMM_ID_QUERY_CURRENT);

    CYGACC_CALL_IF_SET_CONSOLE_COMM(2);

    comm = CYGACC_CALL_IF_CONSOLE_PROCS();
    CYGACC_COMM_IF_WRITE(*comm, T, strlen(T));

    CYGACC_CALL_IF_SET_CONSOLE_COMM(cur);
}
</programlisting>

<para>Beware that if doing something like the above, you should only do
it to a channel which does not have GDB at the other end: GDB ignores
raw data, so you would not see the output.</para>

</section>

<!-- }}} --> 
<!-- {{{ Compatibility -->

<section>
<title>Compatibility</title>

<para>The use of this service is controlled by the option
<literal>CYGSEM_HAL_VIRTUAL_VECTOR_DIAG</literal> which is disabled per default on most
older platforms (thus preserving backwards compatibility with older
stubs). On newer ports, this option should always be set.
</para>
</section>

<!-- }}} -->
<!-- {{{ Implementation Details -->

<section><title>Implementation Details</title>

<para>There is an array of procedure tables (raw comm channels) for each
IO device of the platform which get initialized by the ROM monitor, or
optionally by a RAM startup configuration (allowing the RAM
configuration to take full control of the target).  In addition to
this, there's a special table which is used to hold mangler
procedures.</para>

<para>The vector table defines which of these channels are selected for
console and debugging IO respectively: console entry can be empty,
point to mangler channel, or point to a raw channel. The debugger
entry should always point to a raw channel.</para>

<para>During normal console output (i.e., diagnostic output) the console
table will be used to handle IO if defined. If not defined, the debug
table will be used.</para>

<para>This means that debuggers (such as GDB) which require text streams
to be mangled (O-packetized in the case of GDB), can rely on the ROM
monitor install mangling IO routines in the special mangler table and
select this for console output. The mangler will pass the mangled data
on to the selected debugging channel.</para>

<para>If the eCos configuration specifies a different console channel
from that used by the debugger, the console entry will point to the
selected raw channel, thus overriding any mangler provided by the ROM
monitor.</para>

<para>See hal_if_diag_* routines in hal_if.c for more details of the stream
path of diagnostic output. See <function>cyg_hal_gdb_diag_*()</function> routines in
<filename>hal_stub.c</filename> for the mangler used for GDB communication.</para>

<!--
FIXME: Other special channels are reserved for ethernet communication.
-->

</section>

<!-- }}} -->
<!-- {{{ New Platform Ports -->

<section>
<title>New Platform Ports</title>

<para>Define CDL options <literal>CYGNUM_HAL_VIRTUAL_VECTOR_COMM_CHANNELS</literal>,
<literal>CYGNUM_HAL_VIRTUAL_VECTOR_DEBUG_CHANNEL</literal>, and
<literal>CYGNUM_HAL_VIRTUAL_VECTOR_CONSOLE_CHANNEL</literal>.