hal-calling-if.html

ecos 很好的源代码

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).</P
><P
>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).</P
><DIV
CLASS="SECTION"
><H3
CLASS="SECTION"
><A
NAME="AEN9223">Available Procedures</H3
><P
>This is a brief description of the procedures</P
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
><TT
CLASS="LITERAL"
>CH_DATA</TT
></DT
><DD
><P
>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.</P
></DD
><DT
><TT
CLASS="LITERAL"
>WRITE</TT
></DT
><DD
><P
>Writes the buffer to the device.</P
></DD
><DT
><TT
CLASS="LITERAL"
>READ</TT
></DT
><DD
><P
>Fills a buffer from the device.</P
></DD
><DT
><TT
CLASS="LITERAL"
>PUTC</TT
></DT
><DD
><P
>Write a character to the device.</P
></DD
><DT
><TT
CLASS="LITERAL"
>GETC</TT
></DT
><DD
><P
>Read a character from the device.</P
></DD
><DT
><TT
CLASS="LITERAL"
>CONTROL</TT
></DT
><DD
><P
>Device feature control. Second argument specifies function:</P
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
><TT
CLASS="LITERAL"
>SETBAUD</TT
></DT
><DD
><P
>Changes baud rate.</P
></DD
><DT
><TT
CLASS="LITERAL"
>GETBAUD</TT
></DT
><DD
><P
>Returns the current baud rate.</P
></DD
><DT
><TT
CLASS="LITERAL"
>INSTALL_DBG_ISR</TT
></DT
><DD
><P
>[Unused]</P
></DD
><DT
><TT
CLASS="LITERAL"
>REMOVE_DBG_ISR</TT
></DT
><DD
><P
>[Unused]</P
></DD
><DT
><TT
CLASS="LITERAL"
>IRQ_DISABLE</TT
></DT
><DD
><P
>Disable debugging receive interrupts on the device.</P
></DD
><DT
><TT
CLASS="LITERAL"
>IRQ_ENABLE</TT
></DT
><DD
><P
>Enable debugging receive interrupts on the device.</P
></DD
><DT
><TT
CLASS="LITERAL"
>DBG_ISR_VECTOR</TT
></DT
><DD
><P
>Returns the ISR vector used by the device for debugging
        receive interrupts.</P
></DD
><DT
><TT
CLASS="LITERAL"
>SET_TIMEOUT</TT
></DT
><DD
><P
>Set GETC timeout in milliseconds.</P
></DD
><DT
><TT
CLASS="LITERAL"
>FLUSH_OUTPUT</TT
></DT
><DD
><P
>Forces driver to flush data in its buffers. Note
            that this may not affect hardware buffers
        (e.g. FIFOs).</P
></DD
></DL
></DIV
></DD
><DT
><TT
CLASS="LITERAL"
>DBG_ISR</TT
></DT
><DD
><P
>ISR used to handle receive interrupts from the
	device (see ).</P
></DD
><DT
><TT
CLASS="LITERAL"
>GETC_TIMEOUT</TT
></DT
><DD
><P
>Read a character from the device with timeout.</P
></DD
></DL
></DIV
></DIV
><DIV
CLASS="SECTION"
><H3
CLASS="SECTION"
><A
NAME="AEN9313">Usage</H3
><P
>The standard eCos diagnostics IO functions use the channel
procedure table when <TT
CLASS="LITERAL"
>CYGSEM_HAL_VIRTUAL_VECTOR_DIAG</TT
> 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.</P
><P
>You can also use the table functions directly if desired
(regardless of the <TT
CLASS="LITERAL"
>CYGSEM_HAL_VIRTUAL_VECTOR_DIAG</TT
> 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:</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="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);
}</PRE
></TD
></TR
></TABLE
><P
>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.</P
></DIV
><DIV
CLASS="SECTION"
><H3
CLASS="SECTION"
><A
NAME="AEN9321">Compatibility</H3
><P
>The use of this service is controlled by the option
<TT
CLASS="LITERAL"
>CYGSEM_HAL_VIRTUAL_VECTOR_DIAG</TT
> 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.</P
></DIV
><DIV
CLASS="SECTION"
><H3
CLASS="SECTION"
><A
NAME="AEN9325">Implementation Details</H3
><P
>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.</P
><P
>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.</P
><P
>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.</P
><P
>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.</P
><P
>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.</P
><P
>See hal_if_diag_* routines in hal_if.c for more details of the stream
path of diagnostic output. See <TT
CLASS="FUNCTION"
>cyg_hal_gdb_diag_*()</TT
> routines in
<TT
CLASS="FILENAME"
>hal_stub.c</TT
> for the mangler used for GDB communication.</P
></DIV
><DIV
CLASS="SECTION"
><H3
CLASS="SECTION"
><A
NAME="AEN9335">New Platform Ports</H3
><P
>Define CDL options <TT
CLASS="LITERAL"
>CYGNUM_HAL_VIRTUAL_VECTOR_COMM_CHANNELS</TT
>,
<TT
CLASS="LITERAL"
>CYGNUM_HAL_VIRTUAL_VECTOR_DEBUG_CHANNEL</TT
>, and
<TT
CLASS="LITERAL"
>CYGNUM_HAL_VIRTUAL_VECTOR_CONSOLE_CHANNEL</TT
>.</P
><P
>If <TT
CLASS="LITERAL"
>CYGSEM_HAL_VIRTUAL_VECTOR_DIAG</TT
> is set, make sure the infra diag
code uses the hal_if diag functions:</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
> #define HAL_DIAG_INIT() hal_if_diag_init()
 #define HAL_DIAG_WRITE_CHAR(_c_) hal_if_diag_write_char(_c_)
 #define HAL_DIAG_READ_CHAR(_c_) hal_if_diag_read_char(&#38;_c_)</PRE
></TD
></TR
></TABLE
><P
>In addition to the above functions, the platform HAL must also
provide a function cyg_hal_plf_comms_init which initializes the
drivers and the channel procedure tables.</P
><P
>Most of the other functionality in the table is more or less
possible to copy unchanged from existing ports. Some care is necessary
though to ensure the proper handling of interrupt vectors and timeouts
for various devices handled by the same driver. See PowerPC/Cogent
platform HAL for an example implementation.</P
><DIV
CLASS="NOTE"
><BLOCKQUOTE
CLASS="NOTE"
><P
><B
>Note:: </B
> When vector table console code is <SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>not</I
></SPAN
> used,
the platform HAL must map the HAL_DIAG_INIT, HAL_DIAG_WRITE_CHAR and
HAL_DIAG_READ_CHAR macros directly to the low-level IO functions,
hardwired to use a compile-time configured channel.</P
></BLOCKQUOTE
></DIV
><DIV
CLASS="NOTE"
><BLOCKQUOTE
CLASS="NOTE"
><P
><B
>Note:: </B
> On old ports the hardwired <TT
CLASS="LITERAL"
>HAL_DIAG_INIT</TT
>,
<TT
CLASS="LITERAL"
>HAL_DIAG_WRITE_CHAR</TT
> and
<TT
CLASS="LITERAL"
>HAL_DIAG_READ_CHAR</TT
> implementations will also
contain code to O-packetize the output for GDB. This should
<SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>not</I
></SPAN
> be adopted for new ports! On new ports the
ROM monitor is guaranteed to provide the necessary mangling via the
vector table. The hardwired configuration should be reserved for ROM
startups where achieving minimal image size is crucial.</P
></BLOCKQUOTE
></DIV
></DIV
></DIV
></DIV
><DIV
CLASS="NAVFOOTER"
><HR
ALIGN="LEFT"
WIDTH="100%"><TABLE
SUMMARY="Footer navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
><A
HREF="hal-porting-structure.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="ecos-ref.html"
ACCESSKEY="H"
>Home</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
><A
HREF="hal-porting-coding-conventions.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
>HAL Structure</TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="hal-porting-guide.html"
ACCESSKEY="U"
>Up</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
>HAL Coding Conventions</TD
></TR
></TABLE
></DIV
></BODY
></HTML
>