Manual

This example demonstrates the use of two Slice Cards, XA-SK-GPIO and XA-SK-WIFI slice together with the xSOFTip components for Wi-Fi, SPI, I2C and WebServer to provide access to the GPIO slice features via a simple embedded webserver.

A webpage served from the sliceKIT and accessed in a browser on a host PC has the following demo functions:

• Turn GPIO Slice Card LEDS on and off
• Read the room temperature via the on-board ADC and display on the web page
• Display GPIO Slice Card button press status

Hardware Setup

Import and Build the Application

Running the Demo

Next Steps

• One XA-SK-SCR480 Slice Card
• One Kentec K430WQA-V4-F 480×272 Colour Resisitive Touch Screen with cable

This slice provides power supply electronics and a 40-pin ZIF connector for the included LCD, plus a low cost resistive touch screen controller that interfaces to the LCD and to the XCore via a 2-wire interface. The touch functionality is only accesible when the Slice is placed in the TRIANGLE slot.

The parallel RGB interface is driven directly from the xSOFTip LCD controller component running on the xCORE using 1 16 bit port and 4 1-bit ports. The xSOFTip LCD controller is capable of driving screens with resolutions up to 800×600 (in conjunction with the XA-SK-SDRAM Slice Card and xSOFTip SDRAM controller component).

An Analog Devices Touch Screen Controller ADC is provided on the Slice Card and interfaced to the xCORE via an I2C bus and an interrupt line. This can be used to provide resistive touch co-ordinate information to software applications written for this Slice.

• One XA-SK-SDRAM Slice Card

This slice provides 8 Megebytes of random access memory via an ISSI 6400 Synchronous DRAM. It is suitable for burst access only, random access is possible but performance will be very significantly degraded. The associated SDRAM Controll xSOFTip component can operate this memory at clock speeds up to 40 MHz, yielding an aggregate performance of 80 MBytes/sec.

The SDRAM slice uses a technique of reusing the same XCore GPIO pins for both Address and Data. This optimisation is made possible tahnks to the soft nature of the associated xSOFTip sdram controller component. In addition, a NOR gate on the slice generates the data strobes (UDQM and LDQM on the memory chip) from CAS# and WE#. These features are described more fully in the SDRAM Controller xSOFTip component documentation.

Taken together, these features permit the addition of a high performance SDRAM subsystem to any XCore application using only 20 pins.

• One XA-SK-UART-8 Slice Card

8 Uarts are provided on two 8-bit ports. An RS232 signalling level optn is provided by four SP3222EB RS232 transceivers, each handling 4 tx or 4 rx lines. The EN_N enable pins of the transceivers are controlled by populating a jumper between pins 25 and 26 of header J3. If that jumper is populated then RS232 is disabled and TTL inputs/outputs for all uarts can be accessed via J3, otherwise RS232 inputs/outputs for all uarts can be accessed via J4.

A 1.8432 MHZ oscillator provides a fixed master reference frequency which is input into the XCore on a 1-bit port to allow the sc_multi_uart transmitter module software to obtain precise timing against standard UART baud rates.

Uart channel 0 (RX and TX) can be accessed either via pins 1 and 2 of J3 or J4, or via the DB9 connector. In the latter case, RS232 mode needs to be enabled as above.

• Layer 2 packets can be sent and received independently of layer 3
• Integrated support for high priority Qtagged packets
• Integrated support for 802.1 Qav rate control
• Packet filtering in an independent logical core
• Works on a 400 MHz part

• Uses only 2 logical cores
• High throughput
• Uses lower memory footprint
• Only TCP/IP sourced packets can be transmitted
• 500 MHz parts only (MII core requires 62.5 MIPS)

Functionality
Provides a lightweight IP/UDP/TCP stack
Supported Standards
IP, UDP, TCP, DHCP, IPv4LL, ICMP, IGMP
Supported Devices
Requirements
XMOS Desktop Tools	v12.0 or later
XMOS Ethernet Component	2.2.0 or later

The following Figure shows the architecture of the TCP/IP stack when
attaching to an independent Ethernet MAC through an XC channel:

The server runs on a single logical core and connects to the XMOS Ethernet
MAC component. It can then connect to several client
tasks over XC channels. To enable this option the define
XTCP_USE_SEPARATE_MAC needs to be set to 1 in the
xtcp_conf.h file in your application and run the
xtcp_server()
function.

Alternatively, the TCP/IP server and Ethernet server can be run as
an integrated system on two logical cores. This can be started by
running the ethernet_xtcp_server()
function.

The server will determine its IP configuration based on the arguments
passed into the xtcp_server()
or ethernet_xtcp_server()

function.
If an address is supplied then that address will be used (a static IP address
configuration).

If no address is supplied then the server will first
try to find a DHCP server on the network to obtain an address
automatically. If it cannot obtain an address from DHCP, it will determine
a link local address (in the range 169.254/16) automatically using the
Zeroconf IPV4LL protocol.

To use dynamic address, the xtcp_server()
or
ethernet_xtcp_server()
function can be passed a null to
the ip configuration parameter.

The TCP/IP stack client interface is a low-level event based
interface. This is to allow applications to manage buffering and
connection management in the most efficient way possible for the
application.

Each client will receive events from the server. These events
usually have an associated connection. In addition to receiving
these events the client can send commands to the server to initiate
new connections and so on.

The above Figure shows an example event/command sequence of a
client making a connection, sending some data, receiving some data and
then closing the connection. Note that sending and receiving may be
split into several events/commands since the server itself performs no
buffering.

If the client is handling multiple connections then the server may
interleave events for each connection so the client has to hold a
persistent state for each connection.

The connection and event model is the same from both TCP connections
and UDP connections. Full details of both the possible events and
possible commands can be found in Section API
.

The XTCP API treats UDP and TCP connections in the same way. The only
difference is when the protocol is specified on initializing
connections with xtcp_connect()
or xtcp_listen()
.

New connections are made in two different ways. Either the
xtcp_connect()
function is used to initiate a connection with
a remote host as a client or the xtcp_listen()
function is
used to listen on a port for other hosts to connect to the application
. In either
case once a connection is established then the
XTCP_NEW_CONNECTION event is triggered.

In the Berkley sockets API, a listening UDP connection merely reports
data received on the socket, indepedent of the source IP address. In
XTCP, a XTCP_NEW_CONNECTION event is sent each time data
arrives from a new source. The API function xtcp_close()

should be called after the connection is no longer needed.

When data is received by a connection, the XTCP_RECV_DATA
event is triggered and communicated to the client. At this point the
client must call the xtcp_recv()
function to receive the
data.

Data is sent from host to client as the UDP or TCP packets come
in. There is no buffering in the server so it will wait for the client
to handle the event before processing new incoming packets.

As an alternative to the low level interface, a higher level buffered
interface is available. See section Buffered API
.

When sending data, the client is responsible for dividing the data
into chunks for the server and re-transmitting the previous chunk if a
transmission error occurs.

Note that re-transmission may be needed on
both TCP and UDP connections. On UDP connections, the
transmission may fail if the server has not yet established
a connection between the destination IP address and layer 2
MAC address.

The client can initiate a send transaction with the
xtcp_init_send()
function. At this point no sending has been
done but the server is notified of a wish to send. The client must
then wait for a XTCP_REQUEST_DATA event at which point it
must respond with a call to xtcp_send()
.

After this data is sent to the server, two things can happen: Either
the server will respond with an XTCP_SENT_DATA event, in
which case the next chunk of data can be sent or with an
XTCP_RESEND_DATA event in which case the client must
re-transmit the previous chunk of data.

The command/event exchange continues until the client calls the
xtcp_complete_send()
function to finish the send
transaction. After this the server will not trigger any more
XTCP_SENT_DATA events.

As well as events related to connections. The server may also send
link status events to the client. The events XTCP_IFUP and
XTCP_IFDOWN indicate to a client when the link goes up or down.

The server is configured via arguments passed to the
xtcp_server()
function and the defines described in Section
Configuration Defines
.

Client connections are configured via the client API described in
Section Configuration Defines
.

As an alternative to the low level interface, a buffered interface is
available as a utility layer.

To set up the buffered interface, the application must receive or make
a new connection. As part of the new connection processing a buffer
must be associated with it, by calling xtcp_buffered_set_rx_buffer()

and xtcp_buffered_set_tx_buffer()
.

When sending using the buffered interface, a call to xtcp_buffered_send()

is all that is required. When processing the XTCP_SENT_DATA,
XTCP_REQUEST_DATA and XTCP_RESEND_DATA, the function
xtcp_buffered_send_handler()
should be called.

When processing a XTCP_RECV_DATA event, either the function
xtcp_buffered_recv()
or xtcp_buffered_recv_upto()
can be
called. These either return the data requested, or zero. If some data
is returned, indicated by a non-zero return value, then the application
should process the data, and call the receive function again. Only when
the function returns zero can the application stop trying to receive and
process the data.

Two example applications are provided. app_buffered_protocol_demo shows
the use of the buffered API used with fixed length packets, and
app_buffered_protocol_demo_2 shows the use of the delimited token
mechanism.

The sliceKIT Core Board has four slots with edge conectors: SQUARE, CIRCLE, TRIANGLE and STAR.

To setup up the system:

1. Connect the Ethernet Slice Card to the sliceKIT Core Board using the connector marked with the CIRCLE.
2. Connect the xTAG Adapter to sliceKIT Core Board and connect XTAG-2 to the adapter.
3. Connect the xTAG-2 to host PC. Note that a USB cable is not provided with the sliceKIT starter kit.
4. Plug the power supply into the sliceKIT Core Board and turn the
   power supply on.

1. On your PC, open xTIMEcomposer. You need to be in the
   edit perspective (Window->Open Perspective->XMOS Edit).
   If the XMOS Edit option isn’t in the list, you are
   already in the edit perspective.
2. Locate the 'Simple HTTP Demo' item in the xSOFTip pane on the
   bottom left of the window and drag it into the Project Explorer
   window in the xTIMEcomposer. This will also cause the modules on
   which this application depends to be imported as well.
3. Click on the app_simple_webserver item in the Explorer pane then
   click on the build icon (hammer) in xTIMEcomposer. Check the
   console window to verify that the application has built successfully.

For help in using xTIMEcomposer, try the xTIMEcomposer tutorials, which you can find by selecting Help->Tutorials from the xTIMEcomposer menu.

Note that the Developer Column in the xTIMEcomposer on the right hand
side of your screen provides information on the xSOFTip components you
are using. Select the module_xtcp component in the Project
Explorer, and you will see its description together with API
documentation (reached by double clicking on the Documentation
item within the project). If you view other documentation, you can get
back to this quickstart guide by cliking the back icon in the
Developer Column until you return to this quickstart guide.

Now that the application has been compiled, the next step is to run it
on the sliceKIT Core Board using the tools to load the application
over JTAG (via the XTAG-2 and XTAG Adaptor Card)
into the xCORE multicore microcontroller.

1. Click on the Run icon (the white arrow in the green
   circle). The debug console window in xTIMEcomposer should then
   display the message:

   **WELCOME TO THE SIMPLE WEBSERVER DEMO**
   

   This has been generated from the application code via a call to
   the printstr() function.

2. Connect the sliceKIT Ethernet Slice your network via an ethernet
   cable. The application is configured by default to use DHCP to
   obtain an IP address. If you wish to change this to a static IP
   address edit the main.xc file in the application (you can
   reach this via the Project Explorer in the xTIMEcomposer) and
   change the ipconfig data structure.
3. The console window should display a message like:

   IP Address: 192.168.0.4
   

   the actual IP address will depend on your local network.

4. From a PC connected to the same network, open a web browser and
   open the link:

   http://192.168.0.4
   

   using the IP adress printed out by the application. This should
   display a “hello world” webpage. You have now got the ethernet
   slice up and running.

If the demo does not work try the following:

• Ensure the Ethernet Slice Card is connected to the CIRCLE
  connector of the core board.
• Ensure the slice network cable is fully connected. There are
  activity LEDs next to the ethernet connector that should
  illuminate if connected.
• Ensure that both the PC and Ethernet Slice card are connected to the
  same network and can route to each other. If you are using a
  dynamically allocated address, make sure your DHCP server is
  configured correctly. If using a static address, make sure your PC
  is configured to talk to that address (in Windows you need to
  check your Network Adapter TCP/IP settings).

Look at the Code

Look at Other Examples

Go through this code in detail

on ETHERNET_DEFAULT_TILE:
   ethernet_xtcp_server(xtcp_ports,
                        ipconfig,
                        c_xtcp,
                        1);

on tile[0]: xhttpd(c_xtcp[0]);

void xhttpd(chanend tcp_svr)
{
  xtcp_connection_t conn;
  printstrln("**WELCOME TO THE SIMPLE WEBSERVER DEMO**");
  // Initiate the HTTP state
  httpd_init(tcp_svr);

  // Loop forever processing TCP events
  while(1)
    {
      select
        {
        case xtcp_event(tcp_svr, conn):
          httpd_handle_event(tcp_svr, conn);
          break;
        }

    }
}

typedef struct httpd_state_t {
  int active;      //< Whether this state structure is being used
                   //  for a connection
  int conn_id;     //< The connection id
  char *dptr;      //< Pointer to the remaining data to send
  int dlen;        //< The length of remaining data to send
  char *prev_dptr; //< Pointer to the previously sent item of data
} httpd_state_t;

httpd_state_t connection_states[NUM_HTTPD_CONNECTIONS];

void httpd_init(chanend tcp_svr)
{
  int i;
  // Listen on the http port
  xtcp_listen(tcp_svr, 80, XTCP_PROTOCOL_TCP);

  for ( i = 0; i < NUM_HTTPD_CONNECTIONS; i++ )
    {
      connection_states[i].active = 0;
      connection_states[i].dptr = NULL;
    }
}

void httpd_handle_event(chanend tcp_svr, xtcp_connection_t *conn)
{
  // We have received an event from the TCP stack, so respond
  // appropriately

  // Ignore events that are not directly relevant to http
  switch (conn->event)
    {
    case XTCP_IFUP: {
      xtcp_ipconfig_t ipconfig;
      xtcp_get_ipconfig(tcp_svr, &ipconfig);

#if IPV6
      unsigned short a;
      unsigned int i;
      int f;
      xtcp_ipaddr_t *addr = &ipconfig.ipaddr;
      printstr("IPV6 Address = [");
      for(i = 0, f = 0; i < sizeof(xtcp_ipaddr_t); i += 2) {
        a = (addr->u8[i] << 8) + addr->u8[i + 1];
        if(a == 0 && f >= 0) {
          if(f++ == 0) {
            printstr("::");
           }
        } else {
            if(f > 0) {
              f = -1;
            } else if(i > 0) {
                printstr(":");
            }
          printhex(a);
        }
      }
      printstrln("]");
#else
      printstr("IP Address: ");
      printint(ipconfig.ipaddr[0]);printstr(".");
      printint(ipconfig.ipaddr[1]);printstr(".");
      printint(ipconfig.ipaddr[2]);printstr(".");
      printint(ipconfig.ipaddr[3]);printstr("\n");
#endif
      }
      return;
    case XTCP_IFDOWN:
    case XTCP_ALREADY_HANDLED:
      return;
    default:
      break;
    }

  if (conn->local_port == 80) {
    switch (conn->event)
      {
      case XTCP_NEW_CONNECTION:
        httpd_init_state(tcp_svr, conn);
        break;
      case XTCP_RECV_DATA:
        httpd_recv(tcp_svr, conn);
        break;
      case XTCP_SENT_DATA:
      case XTCP_REQUEST_DATA:
      case XTCP_RESEND_DATA:
          httpd_send(tcp_svr, conn);
          break;
      case XTCP_TIMED_OUT:
      case XTCP_ABORTED:
      case XTCP_CLOSED:
          httpd_free_state(conn);
          break;
      default:
        // Ignore anything else
        break;
      }
    conn->event = XTCP_ALREADY_HANDLED;
  }

void httpd_init_state(chanend tcp_svr, xtcp_connection_t *conn)
{
  int i;

  // Try and find an empty connection slot
  for (i=0;i<NUM_HTTPD_CONNECTIONS;i++)
    {
      if (!connection_states[i].active)
        break;
    }

  if ( i == NUM_HTTPD_CONNECTIONS )
    {
      xtcp_abort(tcp_svr, conn);
    }

  else
    {
      connection_states[i].active = 1;
      connection_states[i].conn_id = conn->id;
      connection_states[i].dptr = NULL;
      xtcp_set_connection_appstate(
           tcp_svr,
           conn,
           (xtcp_appstate_t) &connection_states[i]);

void httpd_free_state(xtcp_connection_t *conn)
{
  int i;

  for ( i = 0; i < NUM_HTTPD_CONNECTIONS; i++ )
    {
      if (connection_states[i].conn_id == conn->id)
        {
          connection_states[i].active = 0;
        }
    }
}

void httpd_recv(chanend tcp_svr, xtcp_connection_t *conn)
{
  struct httpd_state_t *hs = (struct httpd_state_t *) conn->appstate;
  char data[XTCP_CLIENT_BUF_SIZE];
  int len;

  // Receive the data from the TCP stack
  len = xtcp_recv(tcp_svr, data);

  if ( hs == NULL || hs->dptr != NULL)
    {
      return;
    }

  parse_http_request(hs, &data[0], len);

void parse_http_request(httpd_state_t *hs, char *data, int len)
{
  // Return if we have data already
  if (hs->dptr != NULL)
    {
      return;
    }

  // Test if we received a HTTP GET request
  if (strncmp(data, "GET ", 4) == 0)
    {
      // Assign the default page character array as the data to send
      hs->dptr = &page[0];
      hs->dlen = strlen(&page[0]);
    }
  else
    {
      // We did not receive a get request, so do nothing
    }
}

  if (hs->dptr != NULL)
    {
      // Initate a send request with the TCP stack.
      // It will then reply with event XTCP_REQUEST_DATA
      // when it's ready to send
      xtcp_init_send(tcp_svr, conn);
    }

  if (conn->event == XTCP_RESEND_DATA) {
    xtcp_send(tcp_svr, hs->prev_dptr, (hs->dptr - hs->prev_dptr));
    return;
  }

  if (hs->dlen == 0 || hs->dptr == NULL)
    {
      // Terminates the send process
      xtcp_complete_send(tcp_svr);
      // Close the connection
      xtcp_close(tcp_svr, conn);
    }

  else {
    int len = hs->dlen;

    if (len > conn->mss)
      len = conn->mss;

    xtcp_send(tcp_svr, hs->dptr, len);

    hs->prev_dptr = hs->dptr;
    hs->dptr += len;
    hs->dlen -= len;
  }

• Non-blocking SDRAM management.
• Real time servicing of the LCD.
• Touch interactive display
• Image memory manager to simplify handling of images.
• No real time constraints on the application.

The achievable effective bandwidth varies according to the avaliable XCore MIPS. The maximum pixel clock supported is 25MHz.

Slicekit

Display Controller Application

The module_display_controller can be configured via the header display_controller_conf.h. The module requires nothing to be additionally defined however any of the defines can be overridden by adding the header display_controller_conf.h to the application project and adding the define that needs overridding. The possible defines are:

DISPLAY_CONTROLLER_MAX_IMAGES

This defines the storage space allocated to the display controller for it to store image metadata. When an image is registered with the display controller its dimensions and location in SDRAM address space are stored in a table. The define specifies how many entries are allowed in that table. Note, there is no overflow checking by default.

DISPLAY_CONTROLLER_VERBOSE

This define switches on the error checking for memory overflows and causes verbose error warnings to be emitted in the event of an error.

The“module_display_controller“ functionality is defined in

• display_controller_client.xc
• display_controller_internal.h
• display_controller.xc
• display_controller.h
• transitions.h
• transitions.xc

The display controller handles the double buffering of the image data to the LCD as a real time service and manages the I/O to the SDRAM as a non-real time service.

The display controller API is as follows:
.. doxygenfunction:: display_controller
.. doxygenfunction:: image_read_line
.. doxygenfunction:: image_read_line_p
.. doxygenfunction:: image_write_line
.. doxygenfunction:: image_write_line_p
.. doxygenfunction:: image_read_partial_line
.. doxygenfunction:: image_read_partial_line_p
.. doxygenfunction:: register_image
.. doxygenfunction:: wait_until_idle
.. doxygenfunction:: wait_until_idle_p
.. doxygenfunction:: frame_buffer_commit
.. doxygenfunction:: frame_buffer_init

The transition API is as follows:
.. doxygenfunction:: transition_wipe
.. doxygenfunction:: transition_slide
.. doxygenfunction:: transition_roll
.. doxygenfunction:: transition_dither
.. doxygenfunction:: transition_alpha_blend

The transitions use the display controller API.

The module by itself cannot be built or executed separately – it must be linked in to an application. Once the module is linked to the application, the application can be built and tested for driving a LCD screen.

The following should be done in order to link the component to the application project

1. The module name module_display_controller should be added to the list of MODULES in the application project build options.
2. The module name module_lcd should be added to the list of MODULES in the application project build options.
3. The module name module_sdram should be added to the list of MODULES in the application project build options.
4. The module name module_touch_controller_lib should be added to the list of MODULES in the application project build options.
5. The module name module_i2c_master should be added to the list of MODULES in the application project build options.
6. Now the module is linked to the application and can be used directly

The module is built on XDE Tool version 12.0
The module can be used in version 12.0 or any higher version of xTIMEcomposer.

This application demonstrates how the lcd_module is used to write image data to the LCD screen whilst imposing no real time constraints on the application. The purpose of this demonstration is to show how data is passed to the display_controller. This application also demonstrates an interactive display using touch_controller module.

Getting Started

Buffers and Queues

Filtering

Timestamping

The LITE implementation does not support timestamping or multiple
queues/buffering. The MAC will filter packets based on MAC address and
the broadcast bit of the incoming MAC address. Any further filtering
must be done by the single receive client of the ethernet server.

The MAC address used for the server is set on instantiation of the
server (as an argument to the ethernet_server()
function).
This address should be unique for each device. For all XMOS develop
boards, a unique mac address is stored in the one time programmable
rom (OTP). To retreive this address otp_board_info_get_mac
function is provided in the module module_otp_board_info.

For information on programming MAC addresses into OTP please contact
XMOS for detalis.

Installation

Source code can be found across several modules:

• module_ethernet contains the main MAC code
• module_ethernet_smi contains the code for controlling an
  ethernet phy via the SMI configuration protocol
• module_ethernet_board_support contains header files for common
  XMOS development boards allowing easy initialization of port
  structures.

Which modules are compiled into the
application is controlled by the USED_MODULES define in your
application Makefile.

Key Files

This tutorial describes a demo included in the xmos ethernet
package. The demo can be found in the directory app_ethernet_demo and
provides a simple ethernet application that responds to ICMP ping
requests. It assumes a basic knowledge of XC programming. For
information on XMOS programming, you can find reference material at the XMOS website
.

To write an ethernet enabled application for an XMOS device requires
several things:

1. Write a Makefile for our application
2. Provide an ethernet_conf.h configuration file
3. Provide a custom filter function
4. Write the application code that uses the component

Makefile

# The TARGET variable determines what target system the application is
# compiled for. It either refers to an XN file in the source directories
# or a valid argument for the --target option when compiling.

TARGET = SLICEKIT-L2

# The USED_MODULES variable lists other module used by the application.

USED_MODULES = module_ethernet module_ethernet_board_support \
               module_otp_board_info module_slicekit_support

ethernet_conf.h

// Copyright (c) 2011, XMOS Ltd, All rights reserved
// This software is freely distributable under a derivative of the
// University of Illinois/NCSA Open Source License posted in
// LICENSE.txt and at <http://github.xcore.com/>

#ifdef CONFIG_FULL

#define ETHERNET_DEFAULT_IMPLEMENTATION full

#define MAX_ETHERNET_PACKET_SIZE (1518)

#define MAX_ETHERNET_CLIENTS   (4)    

#else

#define ETHERNET_DEFAULT_IMPLEMENTATION lite

#endif

mac_custom_filter

// Copyright (c) 2011, XMOS Ltd, All rights reserved
// This software is freely distributable under a derivative of the
// University of Illinois/NCSA Open Source License posted in
// LICENSE.txt and at <http://github.xcore.com/>

extern int mac_custom_filter(unsigned int data[]);

int mac_custom_filter(unsigned int data[]){
	if (is_ethertype((data,char[]), ethertype_arp)){
		return 1;
	}else if (is_ethertype((data,char[]), ethertype_ip)){
		return 1;
	}

	return 0;
}

Top level program structure

      on ETHERNET_DEFAULT_TILE:
      {
        char mac_address[6];
        otp_board_info_get_mac(otp_ports, 0, mac_address);
        eth_phy_reset(eth_rst);
        smi_init(smi);
        eth_phy_config(1, smi);
        ethernet_server(mii,
                        null,
                        mac_address,
                        rx, 1,
                        tx, 1);
      }

      on ETHERNET_DEFAULT_TILE : demo(tx[0], rx[0]);

Ethernet packet processing

  mac_get_macaddr(tx, own_mac_addr);

#ifdef CONFIG_FULL
  mac_set_custom_filter(rx, 0x1);
#endif

  while (1)
  {
    unsigned int src_port;
    unsigned int nbytes;
    mac_rx(rx, (rxbuf,char[]), nbytes, src_port);
#ifdef CONFIG_LITE
    if (!is_broadcast((rxbuf,char[])) && !is_mac_addr((rxbuf,char[]), own_mac_addr))
      continue;
    if (mac_custom_filter(rxbuf) != 0x1)
      continue;
#endif

    if (is_valid_arp_packet((rxbuf,char[]), nbytes))
      {
        build_arp_response((rxbuf,char[]), txbuf, own_mac_addr);
        mac_tx(tx, txbuf, nbytes, ETH_BROADCAST);
        printstr("ARP response sent\n");
      }

    else if (is_valid_icmp_packet((rxbuf,char[]), nbytes))
      {
        build_icmp_response((rxbuf,char[]), (txbuf, unsigned char[]), own_mac_addr);
        mac_tx(tx, txbuf, nbytes, ETH_BROADCAST);
        printstr("ICMP response sent\n");
      }

Running the application

// NOTE: YOU MAY NEED TO REDEFINE THIS TO AN IP ADDRESS THAT WORKS
// FOR YOUR NETWORK
#define OWN_IP_ADDRESS {192, 168, 1, 178}

PING 192.168.0.3 (192.168.0.3) 56(84) bytes of data.
64 bytes from 192.168.0.3: icmp_seq=1 ttl=64 time=2.97 ms
64 bytes from 192.168.0.3: icmp_seq=2 ttl=64 time=2.93 ms
64 bytes from 192.168.0.3: icmp_seq=3 ttl=64 time=2.91 ms
64 bytes from 192.168.0.3: icmp_seq=4 ttl=64 time=2.96 ms
...

The file ethernet_conf.h may be provided in the application source
code. This file can set the following defines:

ETHERNET_DEFAULT_IMPLEMENTATION

This define can be set to full or lite and determines which
implementation is chosen by default when the application makes
calls to ethernet_server etc.

MAX_ETHERNET_PACKET_SIZE

This define sets the largest packet size in bytes that the ethernet mac
will receive. The default is the largest possible ethernet packet
size (1518 bytes). Setting this to a smaller value will save
memory but restrict the type of packets you can receieve.

NUM_MII_RX_BUF

Number of incoming packets that will be buffered within the MAC.

NUM_MII_TX_BUF

Number of outgoing packets that will be buffered within the MAC.

MAX_ETHERNET_CLIENTS

The maximum number of clients that can be connected to the
ethernet_server()
function via the rx and tx channel arrays.

NUM_ETHERNET_PORTS

The number of ethernet ports to support. Maximum value is 2 in
the current implementation.

ETHERNET_TX_HP_QUEUE

Define this constant to include the high priority transmit queueing
mechanism. This enables frames which have an ethernet VLAN priority
tag to be queued in a high priority queue, which in turn can be
managed with the 802.1qav transmit traffic shaper.

ETHERNET_RX_HP_QUEUE

Define this constant to include high priority reception of ethernet
VLAN priority tagged traffic. This traffic will be queued into a
fast queue and delivered to the clients ahead of non-tagged traffic.

ETHERNET_TRAFFIC_SHAPER

If high priority transmit queueing is in use (see ETHERNET_TX_HP_QUEUE)
then this enables the 802.1qav traffic shaping algorithm.

MII_RX_BUFSIZE_HIGH_PRIORITY

The number of quadlets (4 byte integers) of space in the high
priority receive buffer. The buffer will actually be two full
packets longer than this to avoid the need to be circular. This
constant applies when the high priority receive queue is in use.

MII_RX_BUFSIZE_LOW_PRIORITY

The number of quadlets (4 byte integers) of space in the low
priority receive buffer. The buffer will actually be two full
packets longer than this to avoid the need to be circular. This
constant applies when the high priority receive is in use.

MII_RX_BUFSIZE

The number of quadlets (4 byte integers) of space in the low
priority receive buffer. The buffer will actually be two full
packets longer than this to avoid the need to be circular. This
constant applies when the high priority receive is not in use.

MII_TX_BUFSIZE

The number of quadlets (4 byte integers) of space in the low
priority transmit buffer. The buffer will actually be two full
packets longer than this to avoid the need to be circular.

MII_TX_BUFSIZE_HIGH_PRIORITY

The number of quadlets (4 byte integers) of space in the high
priority transmit buffer. The buffer will actually be two full
packets longer than this to avoid the need to be circular. This
constant applies when the high priority receive is in use.

ENABLE_ETHERNET_SOURCE_ADDRESS_WRITE

By defining this preprocessor symbol, the source MAC address
will be automatically filled in with the MAC address passed
to the port during initialization.

For the FULL implementation, every application is required to
provide this function. It also needs
to be prototyped (or defined as an inline definition) in the header
file mac_custom_filter.h.

• int mac_custom_filter(unsigned int data[])

  This function examines an ethernet packet and returns a filter
  number to allow different clients to obtain different types of packet.
  The function must run within 6us to allow 100Mbit filtering of
  packets.

  Parameters

  • data

    This array contains the ethernet packet. It does not
    include the preamble but does include the layer 2
    header or the packet.

  Returns

  0 if the packet is not wanted by the application or
  a number that can be registed by
  mac_set_custom_filter()
  by a client. Clients
  register a mask so the number is usually made up of a
  bit per unique client destination for the packet.

Depending on the implementation you must supply a different port
structure. The type mii_interface_t will be set to one of this
structures depending on the ETHERNET_DEFAULT_IMPLEMENTATION define.

• mii_interface_full_t

  Structure containing resources required for the MII ethernet interface.

  This structure contains resources required to make up an MII interface. It consists of 7 ports and 2 clock blocks.

  The clock blocks can be any available clock blocks and will be clocked of incoming rx/tx clock pins.

  Structure Members:

  • clock clk_mii_rx

    MII RX Clock Block.

  • clock clk_mii_tx

    MII TX Clock Block.

  • in port p_mii_rxclk

    MII RX clock wire.

  • in port p_mii_rxer

    MII RX error wire.

  • in buffered port:32 p_mii_rxd

    MII RX data wire.

  • in port p_mii_rxdv

    MII RX data valid wire.

  • in port p_mii_txclk

    MII TX clock wire.

  • out port p_mii_txen

    MII TX enable wire.

  • out buffered port:32 p_mii_txd

    MII TX data wire.

• mii_interface_lite_t

  Structure Members:

  • clock clk_mii_rx

    MII RX Clock Block.

  • clock clk_mii_tx

    MII TX Clock Block.

  • in port p_mii_rxclk

    MII RX clock wire.

  • in port p_mii_rxer

    MII RX error wire.

  • in buffered port:32 p_mii_rxd

    MII RX data wire.

  • in port p_mii_rxdv

    MII RX data valid wire.

  • in port p_mii_txclk

    MII TX clock wire.

  • out port p_mii_txen

    MII TX enable wire.

  • out buffered port:32 p_mii_txd

    MII TX data wire.

  • in port p_mii_timing

    A port that is not used for anything, used by the LLD for timing purposes.

    Must be clocked of the reference clock

• void ethernet_server(mii_interface_t &mii, smi_interface_t
  & ?smi, char mac_address[], chanend rx[], int num_rx, chanend tx[], int num_tx)

  Single MII port MAC/ethernet server.

  This function provides both MII layer and MAC layer functionality. It runs in 5 threads and communicates to clients over the channel array parameters.

  The clients connected via the rx/tx channels can communicate with the server using the APIs found in ethernet_rx_client.h and ethernet_tx_client.h

  Parameters

  • mii

    The mii interface resources that the server will connect to

  • mac_address

    The mac_address the server will use. This should be a two-word array that stores the 6-byte macaddr in a little endian manner (so reinterpreting the array as a char array is as one would expect)

  • rx

    An array of chanends to connect to clients of the server who wish to receive packets.

  • num_rx

    The number of clients connected to the rx array

  • tx

    An array of chanends to connect to clients of the server who wish to transmit packets.

  • num_tx

    The number of clients connected to the txx array

  • smi

    An optional parameter of resources to connect to a PHY (via SMI) to check when the link is up.

Packet Receive Functions

Configuration Functions

Packet Transmit Functions

Configuration Functions

These defines can either be set in ethernet_conf.h or
smi_conf.h from within your application directory.

SMI_COMBINE_MDC_MDIO

This define should be set to 1 if you want to combine MDC and MDIO
onto a single bit port.

SMI_MDC_BIT

This defines the bit number on the shared port where the MDC line is.
Only define this if you have a port that drives both MDC and MDIO.

SMI_MDIO_BIT

This defines the bit number on the shared port where the MDIO line is.
Only define this if you have a port that drives both MDC and MDIO.

• smi_interface_t

  Structure containing resources required for the SMI ethernet phy interface.

  This structure can be filled in two ways. One indicate that the SMI interface is connected using two 1-bit port, the other indicates that the interface is connected using a single multi-bit port.

  If used with two 1-bit ports, set the phy_address, p_smi_mdio and p_smi_mdc as normal.

  If SMI_COMBINE_MDC_MDIO is 1 then p_smi_mdio is ommited and p_mdc is assumbed to multibit port containing both mdio and mdc.

  Structure Members:

  • int phy_address

    Address of PHY, typically 0 or 0x1F.

  • port p_smi_mdio

    MDIO port.

  • port p_smi_mdc

    MDC port.

• void smi_init(smi_interface_t
   &smi)

  Function that configures the SMI ports.

  No clock block is needed. Note that there is no deinit function.

  Parameters

  • smi

    structure containing the clock and data ports for SMI.

• void eth_phy_config(int eth100, smi_interface_t
   &smi)

  Function that configures the Ethernet PHY explicitly to set to autonegotiate.

  Parameters

  • If

    eth100 is non-zero, 100BaseT is advertised to the link peer Full duplex is always advertised

  • smi

    structure that defines the ports to use for SMI

• void eth_phy_config_noauto(int eth100, smi_interface_t
   &smi)

  Function that configures the Ethernet PHY to not autonegotiate.

  Parameters

  • If

    eth100 is non-zero, it is set to 100, else to 10 Mbits/s

  • smi

    structure that defines the ports to use for SMI

• void eth_phy_loopback(int enable, smi_interface_t
   &smi)

  Function that can enable or disable loopback in the phy.

  Parameters

  • enable

    boolean; set to 1 to enable loopback, or 0 to disable loopback.

  • smi

    structure containing the ports

• int eth_phy_id(smi_interface_t
   &smi)

  Function that returns the PHY identification.

  Parameters

  • smi

    structure containing the ports

  Returns

  the 32-bit identifier.

• int smi_check_link_state(smi_interface_t
   &smi)

  Function that polls whether the link is alive.

  Parameters

  • smi

    structure containing the ports

  Returns

  non-zero if the link is alive; zero otherwise.

For the sliceKIT Core Board the ethernet slice could be in any of the
four slots. To choose which slot the defines refer to you can set the
define one of the following defines to be 1 in ethernet_conf.h:

• ETHERNET_USE_CIRCLE_SLOT
• ETHERNET_USE_SQUARE_SLOT
• ETHERNET_USE_STAR_SLOT (Not compatible with the 1v1 Core Board)
• ETHERNET_USE_TRIANGLE_SLOT (Not compatible with the 1v1 Core Board)