can.sgml

开放源码实时操作系统源码.

</PROGRAMLISTING>
</SECTION><!-- can-cyg-io-set-config -->
</SECTION><!-- io-can-api-details -->

<SECTION id="io-can-runtime-cfg">  
<TITLE>Runtime Configuration</TITLE>
  
<PARA>
Runtime configuration is achieved by exchanging data structures with the 
driver via the <function>cyg_io_set_config()</function> and 
<function>cyg_io_get_config()</function> functions.
</PARA>

<SECTION>
<TITLE>Device configuration</TITLE>
  
<PROGRAMLISTING>
typedef struct cyg_can_info_st {
    cyg_can_baud_rate_t baud;
} cyg_can_info_t;
</PROGRAMLISTING>

<PARA>
Device configuration is achieved by by exchanging 
<structname>cyg_can_info_t</structname> data structures with the driver 
via the <function>cyg_io_set_config()</function> and 
<function>cyg_io_get_config()</function> functions using the config keys 
<varname>CYG_IO_GET_CONFIG_CAN_INFO</varname> and 
<varname>CYG_IO_SET_CONFIG_CAN_INFO</varname>. 
The field <structfield>baud</structfield> contains a baud rate selection. 
This must be one of the following values:  
</PARA>
  
<PROGRAMLISTING>
CYGNUM_CAN_KBAUD_10
CYGNUM_CAN_KBAUD_20
CYGNUM_CAN_KBAUD_50
CYGNUM_CAN_KBAUD_100
CYGNUM_CAN_KBAUD_125
CYGNUM_CAN_KBAUD_250
CYGNUM_CAN_KBAUD_500
CYGNUM_CAN_KBAUD_800
CYGNUM_CAN_KBAUD_1000
</PROGRAMLISTING>
</SECTION><!-- can-cyg-io-set-config -->
  
<SECTION>
<TITLE>Timeout configuration</TITLE>

<PROGRAMLISTING>
typedef struct cyg_can_timeout_info_st
{
    cyg_uint32 rx_timeout;
    cyg_uint32 tx_timeout;
} cyg_can_timeout_info_t;
</PROGRAMLISTING>

<PARA>
Timeout configuration is achieved by by exchanging 
<structname>cyg_can_timeout_info_t</structname> data structures with the 
driver via the <function>cyg_io_set_config()</function> and 
<function>cyg_io_get_config()</function> functions using the config keys 
<varname>CYG_IO_SET_CONFIG_CAN_TIMEOUT</varname> and 
<varname>CYG_IO_SET_CONFIG_CAN_TIMEOUT</varname>.   
</PARA>

<variablelist>
   <varlistentry>
       <term><type>cyg_uint32</type> <varname>rx_timeout</varname></term>
           <listitem><para>
Timeout for <function>cyg_io_read</function> calls.
          </para></listitem>
   </varlistentry>
   <varlistentry>
       <term><type>cyg_uint32</type> <varname>tx_timeout</varname></term>
           <listitem><para>
Timeout for <function>cyg_io_write</function> calls.
          </para></listitem>
   </varlistentry>
</variablelist>   

<PARA>
Timeout runtime configuration is supported if the configuration options 
<varname>CYGOPT_IO_CAN_SUPPORT_NONBLOCKING</varname> 
and <varname>CYGOPT_IO_CAN_SUPPORT_TIMEOUTS</varname> are enabled. 
</PARA>
</SECTION><!-- can-timeout-config -->

<SECTION>
<TITLE>Reading buffer configuration</TITLE>
    
<PROGRAMLISTING>    
typedef struct cyg_can_buf_info_st
{
    cyg_int32 rx_bufsize;
    cyg_int32 rx_count;
    cyg_int32 tx_bufsize;
    cyg_int32 tx_count;
} cyg_can_buf_info_t;
</PROGRAMLISTING>

<PARA>
<varname>CYG_IO_GET_CONFIG_CAN_BUFFER_INFO</varname> - This function 
retrieves the current state of the software buffers in the CAN drivers. 
For the transmit buffer it returns the the total number of 
<type>cyg_can_message</type> objects in buffer and the current number of 
<type>cyg_can_message</type> objects occupied in the buffer. 
For the receive buffer it returns the total number of 
<type>cyg_can_event</type> objects in receive buffer and the current 
number of <type>cyg_can_event</type> objects occupied in the buffer. 
It does not take into account any buffering such as FIFOs or holding 
registers that the CAN hardware device itself may have.
</PARA>

<variablelist>
   <varlistentry>
       <term><type>cyg_uint32</type> <varname>rx_bufsize</varname></term>
           <listitem><para>
Total number of <type>cyg_can_event</type> buffers in receive queue.
          </para></listitem>
   </varlistentry>
   <varlistentry>
       <term><type>cyg_uint32</type> <varname>rx_count</varname></term>
           <listitem><para>
Current number of <type>cyg_can_event</type> buffers occupied in receive queue.
          </para></listitem>
   </varlistentry>
      <varlistentry>
       <term><type>cyg_uint32</type> <varname>tx_bufsize</varname></term>
           <listitem><para>
Total number of <type>cyg_can_message</type> buffers in transmit queue.
          </para></listitem>
   </varlistentry>
   <varlistentry>
       <term><type>cyg_uint32</type> <varname>rtx_count</varname></term>
           <listitem><para>
Current number of <type>cyg_can_message</type> buffers occupied in transmit queue.
          </para></listitem>
   </varlistentry>
</variablelist>   
</SECTION>  <!-- can-read-buffer-config -->
  
  
<SECTION>
<TITLE>Reading hardware description information</TITLE>
    
<PROGRAMLISTING>    
typedef struct cyg_can_hdi_st
{
    cyg_uint8 support_flags;
    cyg_uint8 controller_type;
} cyg_can_hdi;
</PROGRAMLISTING>

<PARA>
<varname>CYG_IO_GET_CONFIG_CAN_HDI</varname> - This function retrieves 
information about the used hardware. The Hardware Description Interface 
provides a method to gather information about the CAN hardware and the 
functionality of the driver. For this purpose the structure 
<structname>cyg_can_hdi</structname> is defined.  
</PARA>
     
<variablelist>
   <varlistentry>
       <term><type>cyg_uint8</type> <varname>support_flags</varname></term>
           <listitem><para>
Contains information about the capabilities of the used CAN hardware.
          </para></listitem>
   </varlistentry>
   <varlistentry>
       <term><type>cyg_uint8</type> <varname>controller_type</varname></term>
           <listitem><para>
A number that identifies the CAN controller type.
          </para></listitem>
   </varlistentry>
</variablelist>

<PARA>
The following flags are available in the field <structfield>support_flags</structfield>:  
</PARA>
     
<PROGRAMLISTING>    
|   7   |   6   |   5   |   4   |   3   |   2   |   1   |   0   |
+-------+-------+-------+-------+-------+-------+-------+-------+
|  res  |  res  |  res  |timest.|SW-Filt|FullCAN|   Frametype   |
</PROGRAMLISTING>

<variablelist>
  <varlistentry>
    <term><parameter>Frametype</parameter></term>
    <listitem><para>
Bit 0 and Bit 1 of the structure describe the possibilities of the CAN
controller. The following values are defined:
    <PROGRAMLISTING>    
CYGNUM_CAN_HDI_FRAMETYPE_STD          // receives only standard frame
CYGNUM_CAN_HDI_FRAMETYPE_EXT_PASSIVE  // can receive but not send extended frames
CYGNUM_CAN_HDI_FRAMETYPE_EXT_ACTIVE   // can send and receive extended frames
    </PROGRAMLISTING>
    </para></listitem>
  </varlistentry>
    <varlistentry>
    <term><parameter>FullCAN</parameter></term>
    <listitem><para>
If the Bit 2 - <varname>CYGNUM_CAN_HDI_FULLCAN </varname> - is set to one, 
the CAN controller supports more than one message buffer.
    </para></listitem>
  </varlistentry>
  <varlistentry>
    <term><parameter>SW-Filter</parameter></term>
    <listitem><para>
If Bit 3 - <varname>CYGNUM_CAN_HDI_FILT_SW</varname> - is set to one then 
the CAN driver supports some kind of software message filtering.
    </para></listitem>
  </varlistentry>
  <varlistentry>
    <term><parameter>Timestamp</parameter></term>
    <listitem><para>
If Bit 4 - <varname>CYGNUM_CAN_HDI_TIMESTAMP</varname> - is set to one then 
the CAN hardware supports timestamps for CAN messages
    </para></listitem>
  </varlistentry>
</variablelist>
</SECTION>  <!-- can-read-buffer-config -->
   
<SECTION>
<TITLE>Reading hardware message buffer configuration</TITLE>
<PROGRAMLISTING>    
typedef struct cyg_can_msgbox_info_st
{
    cyg_uint8 count; // number of message buffers available for this device
    cyg_uint8 free;  // number of free message buffers
} cyg_can_msgbuf_info;
</PROGRAMLISTING>
   
<PARA>
<varname>CYG_IO_GET_CONFIG_CAN_MSGBUF_INFO</varname> - If the CAN hardware supports 
more than one message buffer for reception of CAN messages (flag 
<varname>CYGNUM_CAN_HDI_FULLCAN</varname> is set while reading hardware description 
interface with <varname>CYG_IO_GET_CONFIG_CAN_HDI</varname>) then this function 
reads the number of message buffers the CAN hardware supports and the number of 
free message buffers.   
</PARA>

<variablelist>
   <varlistentry>
       <term><type>cyg_uint8</type> <varname>count</varname></term>
           <listitem><para>
Counts the number of message buffers supported by the device.
          </para></listitem>
   </varlistentry>
   <varlistentry>
       <term><type>cyg_uint8</type> <varname>free</varname></term>
           <listitem><para>
Contains the number of free message buffers. The free message buffers are 
available for setting up remote buffers (<varname>CYG_IO_SET_CONFIG_CAN_REMOTE_BUF</varname>) 
and message filters (<varname>CYG_IO_SET_CONFIG_CAN_FILTER_MSG</varname>).
          </para></listitem>
   </varlistentry>
</variablelist>   
</SECTION> <!-- can-read-buffer-config -->
   
<SECTION>
<TITLE>Reading state of CAN hardware</TITLE>

<PROGRAMLISTING>    
typedef enum
{
  CYGNUM_CAN_STATE_ACTIVE,      // CAN controller active, no errors
  CYGNUM_CAN_STATE_STOPPED,     // CAN controller in stopped mode
  CYGNUM_CAN_STATE_STANDBY,     // CAN controller in Sleep mode
  CYGNUM_CAN_STATE_BUS_WARN,    // CAN controller active, warning level is reached
  CYGNUM_CAN_STATE_ERR_PASSIVE, // CAN controller went into error passive mode
  CYGNUM_CAN_STATE_BUS_OFF,     // CAN controller went into bus off mode
  CYGNUM_CAN_STATE_PHY_FAULT,   // General failure of physical layer 
  CYGNUM_CAN_STATE_PHY_H,       // Fault on CAN-H detected (Low Speed CAN)
  CYGNUM_CAN_STATE_PHY_L,       // Fault on CAN-L detected (Low Speed CAN)
} cyg_can_state;
</PROGRAMLISTING>

<PARA>
<varname>CYG_IO_GET_CONFIG_CAN_STATE</varname> - This function retrieves the 
present state of the CAN controller. Possible values are defined in the 
<type>cyg_can_state</type> enumeration.
</PARA>   
</SECTION> <!-- can-read-hw-state -->


<SECTION>
<TITLE>Changing mode of CAN hardware</TITLE>

<PARA>
<varname>CYG_IO_SET_CONFIG_CAN_MODE</varname> - This function changes 
the operating mode of the CAN controller. The identifiers for the different 
operating modes are defined in the <type>cyg_can_mode</type> enumeration.
</PARA>

<PROGRAMLISTING> 
typedef enum
{
  CYGNUM_CAN_MODE_STOP,   // set controller into stop mode
  CYGNUM_CAN_MODE_START,  // set controller into operational mode
  CYGNUM_CAN_MODE_STANDBY // set controller into standby / sleep mode
} cyg_can_mode;
</PROGRAMLISTING>
 
<variablelist>
   <varlistentry>
       <term><type>CYGNUM_CAN_MODE_STOP</type></term>
           <listitem><para>
Set controller into stop mode
          </para></listitem>
   </varlistentry>
   <varlistentry>
       <term><type>CYGNUM_CAN_MODE_START</type></term>
           <listitem><para>
Set controller into operational mode
          </para></listitem>
   </varlistentry>
   <varlistentry>
       <term><type>CYGNUM_CAN_MODE_STANDBY</type></term>
           <listitem><para>
Set controller into standby / sleep mode.
          </para></listitem>
   </varlistentry>
</variablelist>

<PARA>
Before the hardware configuration of the device is changed, that means
if baud rate is changed or the message buffer and filter configuration
is changed, the CAN hardware should be set into stop mode and if
configuration is finished, then device should be set back into
operational mode.  Before the device is set into standby mode, the
output buffers should be flushed or drained because transmission of a
CAN message may wake up the CAN hardware. If a received message wakes
up the CAN hardware from standby mode then
a <varname>CYGNUM_CAN_EVENT_LEAVING_STANDBY</varname> event will be
inserted into receive message buffer or
the <varname>CYGNUM_CAN_EVENT_LEAVING_STANDBY</varname> flag will be
set for the message that caused wake up of CAN hardware.
</PARA>
</SECTION> <!-- can-mode-cfg -->
   
<SECTION>
<TITLE>Flush or drain buffers</TITLE>

<PARA>
<varname>CYG_IO_SET_CONFIG_CAN_OUTPUT_DRAIN</varname> - This function
waits for any buffered output to complete. This function only