Draft 2

The firmware for a channel determines the header size and maximum payload size for the channel's frames. Normally this will be a function of the type of channel and the firmware version. These numbers describe the frames as received from the medium; the buffers allocated for the frames will also include space for system overhead.

The same software may be able to handle several different combinations of firmware version, header size and max payload size so the same code container name may appear in more than one table entry. The code is loaded only once but a separate factory instance is created for each entry

The Data Paths table

The lanes (MGTs) allocated to a channel will all feed a particular output (pipe) on the backplane. Those channels that have no lanes will not appear in this table.

typedef uint32_t StringOff; // Offset within the Strings table.

struct Channel {
    uint32_t  key;
    unit32uint32_t  officialTypefactoryKey;     // TheRef. officialto channelFactories type numbertable.
    unit32_t  lanesUsed;      // Bit-mask of lanes used.
    uint32_t  pibsUsed;       // Bit-mask of Pending Import Blocks used.
    uint32_t  pebsUsed;       // Bit-mask of Pending Export Blocks used.
    uint32_t  ecbsUsed;       // Bit-mask of Event Completion Blocks used.
    uint32_t  flbsUsed;       // Bit-mask of Free List Blocks used.
    uint32_t  numPorts;       // Size of port-number space.
    StringOff description;
};

struct Factory {
    uint32_t  key;
    uint32_t  channelTypeNum;
    uint32_t  containerName;
    StringOff description;
};

struct DataPath { Factory {
    uint32_t  key;
    unit32_t  typeNumber;      // The official channel type number.
    uint32_t  key;firmwareVersion; // Firmware version number.
    uint32_t  channelKey;headerSize;      // Bytes.
    uint32_t  pipeNummaxPayloadSize;    // WhereBytes.
  the channel's signals "come out." uint32_t  containerName;
};

The

Data Paths table

Each channel comes with a recommendation for the number and size (in bytes) of buffers to be allocated in non-cached memory. Those recommendations are in this table. Note that these are only recommendations ; the system initialization procedure needs to consider all the recommendations together along with the amount of memory actually available.The lanes (MGTs) allocated to a channel will all feed a particular output (pipe) on the backplane. Those channels that have no lanes will not appear in this table.

struct BufferDataPath {
    uint32_t  key;
    uint32_t  channelKey;
    uint32_t  bufferCount;
    uint32_t bufferSize;pipeUsed;    // Where the channel's signals "come out."
};

Example configuration tables

Here's what the tables would look like for an RCE that defines nothing but an ethernet LAN and configuration flash, which are standard for all RCEs. We assume that the ethernet uses lanes 0-3, PIB 0, PEB 0, ECB 0, FLB0 and feeds pipe 54.

The Channels table:

Ethernet allows 65536 ports so as not to restrict the port space of UDP or TCP.

The Factories table:

The Data Paths table:

The Buffers table:

Here we assume that the firmware delivers all ethernet framing bytes as well as the payload and that jumbo frames are not allowed. We assume that the formware delivers configuration flash data in units of pages and that a page is 2K bytes long.

How the tables appear in RAM

We copy the tables without alteration and set the members of an instance of the following structure:

struct Tables {
    unsigned numChannels;
    Channel *channel;      // Pointer to first element of table.
    unsigned numFactories;
    Factory *factory;
    unsigned numDataPaths;
    DataPath *dataPath;
    unsigned numBuffers;
    Buffer *buffer;
};

The Data Paths table:

How the tables appear in RAM

We copy the tables without alteration and set the members of an instance of the following structure:

struct Tables {
    unsigned numChannels;
    Channel *channel;      // Pointer to first element of table.
    unsigned numFactories;
    Factory *factory;
    unsigned numDataPaths;
    DataPath *dataPath;
};

Use case: System startup

We'll need to use a quick and dirty way to read the configuration tables from flash; either that or just use faked-up configuration tables to create the config. flash Channel object. Once we can have that we can create the rest of the Channel objects.

1. Boot code
   1. Loads and starts the system core.
2. System core
   1. Initializes the CPU.
   2. Initializes RTEMS.
   3. Initializes any extra C++ support.
   4. Sets up the MMU's TLB and enables the MMU.
   5. Uses a basement level technique to read the tables from configuration flash.
   6. Creates and registers the channel factory for configuration flash.
   7. Creates and registers the configuration flash channel.
   8. Allocates frame buffers in uncached RAM for config. flash pages.
   9. Gives the frame buffers to the configuration flash channel and enables it.
   10. Creates the default instance of the dynamic linker.
   11. Loads and links the factory code marked as loadable in the Factories table.
   12. Calls the entry points in the factory code modules just loaded.
   13. Iterates on the Channels table and creates all Channel objects.
   14. Iterates over all Channel objects (except config. flash) to get their recommended buffer allocations.
   15. Allocate the buffers in uncached memory.
   16. Assigns buffers to channels.
   17. Enables all Channel objects not already enabled.
   18. Loads and links the application code using the default dynamic linker.
   19. Initializes the network.
       1. Initializes each ethernet channel.
       2. Initializes IP, UDP, TCP and BSD sockets.
       3. Gets a DHCP lease if required.
   20. Calls the application entry point.
3. Factory code entry point.
   1. Creates a channel factory object using the given configuration table info as input.
   2. Registers the object with the core.

Use case: Frame import

TBD.

Use case: Frame export

TBD.

Low-level API

Official RCE channel type numbers

These are given in a header file made available to both core and application code. The numbers are members of an enumeration.

namespace RCE::chantype {

    enum {
        ETHERNET,
        CONFIG_FLASH,
        CATCH_ALL,
        ...
    } Number;
}

Channel factory registry

An instance of this class will be exported by the core code using some design pattern such as Singleton or functional equivalent. This instance is created during system startup and lasts until system shutdown. Assignment or copying of instances is forbidden.

class ChannelFactoryRegistry {

    ChannelFactoryRegistry();

    // Register a factory and assign it a sequence number i starting from zero.
    // The argument may not be a null pointer.
    void addFactory(ChannelFactory*);

    int numFactories();

    // If i is a valid sequence number then return the i'th factory
    // else return a null pointer.
    ChannelFactory* factory(int i);

);

Channel registry

An instance of this class will be exported by the core code using some design pattern such as Singleton or functional equivalent. This instance is created during system startup and lasts until system shutdown. Assignment or copying of instances is forbidden.

class ChannelRegistry {

    ChannelRegistry();

    // Register a channel and assign it a sequence number i starting from zero.
    // The argument may not be a null pointer.
    void addChannel(Channel*);

    int numChannels();

    // If i is a valid sequence number then return the i'th channel
    // else return a null pointer.
    Channel* factory(int i);

);

Use case: System startup

1. Boot code
   1. Loads and starts the system core.
2. System core
   1. Initializes the CPU.
   2. Initializes RTEMS.
   3. Initializes any extra C++ support.
   4. Sets up the MMU's TLB and enables the MMU.
   5. Registers the factories for configuration flash and catch-all.
   6. Creates the configuration flash channel.
   7. Allocates uncached RAM for config. flash pages.
   8. Enables the configuration flash channel.
   9. Copies the Channels table and related info from configuration flash into RAM.
   10. Creates the default instance of the dynamic linker.
   11. Loads and links the factory code marked as loadable in the Factories table.
   12. Calls all factory code entry points so that all factories are registered.
   13. Walks the Channels table and creates all Channel objects.
   14. Walks the Buffers table and allocates uncached memory for I/O buffers.
   15. Assigns buffers to channels.
   16. Enables all Channel objects not already enabled.
   17. Loads and links the application code using the default dynamic linker.
   18. Initializes the network.
       1. Initializes each ethernet channel.
       2. Initializes IP, UDP, TCP and BSD sockets.
       3. Gets a DHCP lease if required.
   19. Calls the application entry point.
3. Factory code entry point.
   1. Registers with the core an object that creates the right kind of Channel objects.

Use case: Frame import

TBD.

Use case: Frame export

TBD.

Low-level API

Official RCE channel type numbers and names

These are given in a header file made available to both core and application code. The numbers are members of an enumeration and the names+descriptions are given in a static array.

namespace RCE::chantype {

    enum {
        ETHERNET,
        CONFIG_FLASH,
        CATCH_ALL,
        ...
    } Numbers;

    const char *name = {
        "eth",
        "config",
        "catch-all"
        ...
    };

    const char *description = {
        "ethernet",
        "configuration flash",
        "catch-all channel",
        ...
    };
}

Channel factory

The abstract base class for objects that manufacture Channel instances. Channel factories are created during system startup and last until system shutdown. Assignment or copying of instances is forbidden.

class ChannelFactory {
public:

    ChannelFactoryRCE::chantype::Number typeNumber() const;

    virtualconst Channelchar* createChanneltypeName(
        unsigned ident,) const;

    unsigned firmwareVersion() const;

    unsigned headerSize() const;

  // Assigned by init. code.unsigned maxPayloadSize() const;

    unsigned numBuffersAdvised() const;

    unsigned channelTableKey,codeContainerName() const;

    const    RCE::config::Tables&) = 0;
char* description() const;

    virtual ~ChannelFactory();
};

Channel type registry

An instance of this class will be exported by the core code using some design pattern such as Singleton or functional equivalent. This instance is created during system startup and lasts until system shutdown. Assignment or copying of instances is forbidden.

class ChanneTypeRegistry {

    ChannelTypeRegistry();

    // Register a Channel factory using its official RCE type number.
    void registerChannelFactoryChannel* createChannel(
        unsigned channelTableKey,
        RCE::config::Tables&
    ) = 0;

protected:

    ChannelFactory(
        unsigned officialNumberfactoryTableKey,
         ChannelFactory const RCE::config::Tables&,
	const char*   );

    ChannelFactory& channelFactory(unsigned officialNumbertypeName,
	unsigned numBuffersAdvised,
	const char *description
    );

    unsignedvirtual officialNumber(const char *officialName~ChannelFactory();
)};

Channel

A channel object manages a set of I/O buffers and a particular instance of a protocol plug-in. At the beginning of each buffer the channel will build a SuperFrame FrameBuffer object. Each channel object is created at system startup, initially in a disabled state. Afterward the system startup code will allocate the buffers, feed them to the channel objects and then enable them. Channel objects live until system shutdown.

Each channel creates and destroys Port objects on demand. Each port is assigned a unique ID numberone of the channel's legal port numbers not used by any other port. The client code may request a particular ID in the legal range port number for the type of channel, e.g., a well-known TCP port number. The client may also allow the channel to assign an ID not currently in use by any port.

A channel knows how to derive a port number from the header of a frame it has received.

Channel and its derived classes do not allow copying or assignment of their instances.

class Channel {
public:

    ChannelFactory* factory() const; // Set the system's channel ID and the channel type number. Leaves
  // the Channel in the disabled state.
  Channel(unsigned systemAssignedId, unsigned typeNum);

  unsigned idThe factory that created me.

    unsigned lanesUsed() const;

    unsigned pibsUsed() const;

    unsigned pebsUsed() const;

    unsigned ecbsUsed() const;

    unsigned flbsUsed() const;

    unsigned pipeUsed() const;

    const char* description() const;


    unsigned typeNumorphanFrameCount() const;

    // Create a Port with a specified port number.
    // Returns 0null if the number is already taken.
    virtual Port* createPort(int portNum) = 0;

    // Create a Port with a number assigned by the channel.
    // Returns 0null if no port number is free.
    virtual Port* createPort() = 0;

    virtual void destroyPort(Port *) = 0;

    // Return 0null or the Port with the given number.
    Port *findPortgetPort(unsigned portNum) const;

  // Manage a new buffer.
  void addBuffer(void *);

  // Reclaim a buffer that was given out by// oneStart ofmanaging thea Ports
new buffer //or createdreclaim byan thisold channelone.
    void reclaimBufferclaimBuffer(void *);

    void enable();

    void disable();

    void isEnabled() const;

    // Return null or a pointer to the Port that should
    // Returnreceive -1 or the number of the port to which the frame should go,
  // assuming the frame belongs to this channel.
  virtual int getPortNumber(void *frameHeader) const;

  virtual unsigned frameHeaderSize() const;

protected:

  // Does nothing because Channels last until the next system shutdown.the data.
    virtual Port* deducePort(void *frameHeader) const;

protected:
    // Create a Channel which is initially in the disabled state.
    Channel(
        unsigned channelTableKey,
        RCE::config::Tables&,
	ChannelFactory *,
    );

  virtual ~Channel();

};

Port

Remembers the Channel that created it.

Allows client code to wait for new frames.

Reclaims frames frame buffers that the client code has finished using AND that were provided by this particular port(or has just
created).

class Port {
public:
  Port(Channel &*, unsigned portNumportNumber);
  Channel&* channel() const;
  unsigned portNumportNumber() const;
  virtual void* wait(); // Returns a pointer to the frame header when one becomes available.
  void reclaimBufferclaimBuffer(void *frameHeader) const;
};

API implementation classes

These classes are not exposed to the client but are used internally by the API.

Class

FrameBuffer

A SuperFrame FrameBuffer instance is placed at the beginning of a buffer that will also hold the frame proper immediately after the SuperFrame. The instances are created at system startup and live until system shutdown.

A SuperFrame FrameBuffer contains regions of fixed size used in the management of the frame itself and its buffer:

• One or more links used to make singly-linked lists.
• The firmware's in-memory descriptor. The firmware TDE for the frame points to the descriptor.
• Status. The firmware writes operation completion status here.

Immediately following the end of the SuperFrame FrameBuffer buffer in we have first the frame's header and then its payload.

The links, descriptor and status areas have the same sizes for all channel types.

The descriptor must begin on a 64-byte boundary; for ease of layout the entire buffer also has that alignment. The buffer should also begin on a cache line boundary in order to reduce cache thrashing but since a cache line is only 32 bytes long this requirement is already met.

SuperFrame is used internally by the API; no client code is ever given any of its instancesFrameBuffer instances may not be copied or assigned.

class SuperFrameFrameBuffer {
public:
    SuperFrameFrameBuffer(void *bufferAddress);
    SuperFrameFrameBuffer* link(unsigned linkNum) const;
    const Descriptor& descriptor() const;
    const OpStatus& status() const;
    char* header() const;
    char* payload() const;
private:
    SuperFrameFrameBuffer* link[N];
    Descriptor descr;
    OpStatus status;
    // The frame header starts here.
};