| Option | Description |
| -help | Displays usage information. |
| -version | Displays version information. |
| -nolog | Disables logging to idlv.log. |
| -config | Specifies a configuration file to be used by the compiler. More than one configuration file can be specified. These files contain compiler options. |
| [-idl] | Specifies an IDL file. Multiple IDL files can be presented to the compiler. This is an optional switch; you can omit this switch and just give the name of the IDL file. |
| -D name | Passas a macro definition to the parser. |
| -D= | Passas a macro definition with value to the IDL parser. |
| -I | Add directory to the list of include directories. |
| -o | The directory in which the compiler will place the generated files. If not specified, the compiler will use the current directory. |
| -overwrite | If specified, overwrite the user-modifiable output i.e. clients/servers, GPIO records and top-level entity. The default behaviour is to keep the existing files and generate new files with a new numeric suffix. |
| -notimestamps | Suppress the time stamp information in header file comments. |
| -nodefaultobjects | Do not generate the default server or bridges. |
| -notle | Do not generate the top level entity. |
| -nostandard | Disable support for standard operations (is_a, non-existent). |
| -library | Use libraryfor the compiler output (default is work). |
| -dryrun | Do not generate any output; list to the console the filenames that would have been created. |
| -server | Generate a server entity with the name server; the TLE will instantiate instances of this server. The server will implement the modules/interfaces/operations in. |
| -client | Generate a client entity with the name client; the TLE will instantiate instances of this client. The client will implement the modules/interfaces/operations in. |
| -sysexc | Add client/server support for system exceptions.is a comma-separated list of names from the following:INTERNALNO_RESOURCESCOMM_FAILURENO_IMPLEMENTMARSHALINV_OBJREFBAD_PARAMOBJECT_NOT_EXISTIMP_LIMITBAD_OPERATION |
| -bridge | Generatespair(s) of input/output bridges with entity names of ipb_and opb_.input_endian : endian nature of the input bridge, one of little, big or auto .output_endian : endian nature of the output bridge: either little or big .check_INV_OBJREF : true/false to enable/disable handling of the INV_OBJREF system exception in the input bridge .check_OBJECT_NOT_EXIST : true/false to enable/disable handling of the OBJECT_NOT_EXIST system exception in the input bridge .check_BAD_OPERATION : true/false to enable/disable handling of the BAD_OPERATION system exception in the input bridge. |
| -default_ipb_endianlittle|big|auto-default_opb_endian little|big | Sets the endian nature for the default input and output bridge respectively. These settings will only be in effect if the default bridges are used (e.g. if no custom bridge specifications are provided using the -bridge option).Default input bridge endian: autoDefault output bridge endian: big |
| -enable_connections | Enable multiple connection support. |
| -enable_objectkey | Enable the generation of signals for the provision of object key data for outgoing CORBA requests. |
| -any_limit | For outgoing requests from clients and outgoing replies/user exceptions from servers, the maximum number of ‘any’ type parameters (including within sequences) in that request/reply/user exception. |
# File names on the command line
If the path for the output directory or the file name for an IDL file or configuration file contains spaces then the path/file name must be enclosed in double quotes. This is not required for options in a configuration file. For example:
```batch
idlv -o "c:\dev\compiler output" "c:\dev\test file.idl"
```
# Configuration file
A text file containing one compiler option per line. The options are the same as the command line options, except that the -idl option for IDL files is required. Multiple configuration files can be specified. The compiler parses the command line left to right, processing configuration files as they are encountered.
# Clients, servers and hybrid bus objects
Bus objects are specified by the nature (client or server), a name, a count and an implementation list. The name is used as part of the VHDL instance name; the count is the number of instances that the TLE will instantiate; and the implementation list is a comma-delimited list of modules/interfaces/operations that the bus object will implement. Specifying a module will implement all the interfaces within that module (and any child modules). Specifying ‘all’ will implement all interfaces within all IDL files.
Multiple specifications for the same name are permitted and a bus object can be both a client and a server. The highest count given will be used for the number of instantiations in the TLE, and the implementation lists are combined separately for client and server roles.
The instance names start with $\mathsf { \bar { c } 1 i e n t \underline { { \tau } } }$ if the bus object only acts as a client, ‘server\_’ if the bus object only acts as a server or ‘hybrid\_’ if the bus object acts as both. The name given in the specification follows. If the count is greater than one, an underscore and numeric suffix are added.
# 5.4 Limitations
The following limits are built into ICO:
• A maximum total of 255 generated servants, clients and bridges.
• A maximum of 65000 total parameters across all implemented interfaces.
• Connection IDs are represented by an 8-bit value.
# 5.5 Compiler Output
The files generated by the compiler are divided into two groups, depending on whether the user is expected to modify the files. By default the compiler will preserve user-modifiable files by adding numeric suffixes to the file names during later compilation runs where the output is sent to the same directory. This behaviour can be changed by using the -overwrite option.
Table 5 User-modifiable Files
| File name | Description |
| client_.vhdserver_.vhdhybrid_.vhd | These files contain the client/server/hybrid code, whereis the name used in the client/server specification. If no client/server specifications were given on the command line, the compiler generates a default server that implements all interfaces in the given IDL file(s). |
| ico_tle.vhd | This file is the top level entity for ICO. It instantiates the clients, servers, receive and transmit bridges; sets up support for standard operations (if required); and constructs the bus-based architecture. |
| gpio_pkg.vhd | This file contains the record definitions used for the General Purpose Input/Output mechanism (GPIO). GPIO allows clients and servers to communicate directly with each other or on-board resources, and is explained in Section 5.7, User Input/Output, on page 48. |
Table 6 Immutable Files
| File name | Description |
| _pkg.vhd_pkg.vhdidl_pkg.vhd | As explained in Section 4.2.3,Module/Interface Mapping, on page 30,a VHDL package is generated for each module and interface within the IDL and for each IDL file. The packages contain the constants and enumerations defined at that level, along with the address offsets for exceptions that are raised by the clients and servers. In addition, the package for an interface contains the address offsets for the operations in the interface. |
| compiler_metrics_pkg.vhd | This file contains various metrics for the compilation. |
| input_metadata.vhd | The input metadata file is used by the receive bridges to process the data for incoming requests. |
| output_metadata.vhdoutymetadata_strings_pkg.vhd | The output metadata files are used by the transmit bridges to construct outgoing requests. |
| server_types.vhdperfect_hash.vhd | These files contain two entities that are used when handling an incoming request. |
| isa_matcher.vhd | This file contains an entity used by the mechanism that provides the is_a functionality. |
| object_keys_pkg.vhd | This file contains constants for each allocated object key. Each client, server and transmit bridge has a unique object key value. This key value is the base value used in forming an address to put on the address bus. |
| initial_references.txt | This is a text file containing corbaloc initial references for the servers. The protocol, host and endpoint components are placeholders: the user will need to specify the actual values when passing a corbaloc reference to ICO. |
# 5.6 Generated Client/Server Entity Signals
Table 7 Generated Entity Signals
| Signal Name | I/O | Description | Managed |
| reset_n | I | Reset signal. This signal is active low and asynchronous. | Yes |
| clk | I | Clock signal. | Yes |
| q.bus_request | O | Asserted when the entity requires access to the output bus. | Yes |
| d.bus_grant | I | Asserted when the arbitration permits access to the output bus. | Yes |
| q.busy | O | Asserted when the component is busy and cannot start handling a new request or reply. | Yes |
| q.addr | O | Address to send data. | Yes |
| q.data | O | Data to send. 32 bits. User data is sent using this signal. | Yes |
| q.wr | O | Asserted when q.data is valid. | Yes |
| d.addr | I | Address on input bus. Each entity will occupy part of the available address range. | Yes |
| d.data | I | Data on input bus. 32 bits. User data is supplied on this signal. | Yes |
| d.wr | I | Asserted when d.data is valid. | Yes |
| user_out | O | User output record. The record contents are user definable. The record is wired as an output on the generated TLE. The user record is modified by setting the value of the fields in the variable v.outputISCO. | No |
| user_in | I | User input record. The record contents are user definable. This record is is wired as an input on the generated TLE. | No |
Generated client and servant entities have identical interfaces (see Table 7). All of the signals with the exception of the User I/O signals are managed by the generated code.
# 5.7 User Input/Output
The interface between client and servers and the user’s FPGA application logic is provided by User I/O. The User I/O mechanism provides each client and server with VHDL records that contain arbitrary input and output signals. These records are generated by the compiler and are part of the port lists for the clients, servers and TLE. The default contents of the records is a single std\_logic signal; the user replaces this with the designed signals and connects them as required.
# 5.7.1 User I/O VHDL records
The compiler produces two User I/O records for each client/server specification. The record definitions are placed in the VHDL package file generated for the client or server.
If not all clients or not all servers for a particular client/server specification are to share the same GPIO signals, the user can add duplicate client/server specifications as needed. For instance, if five clients are required that have a common client specification (e.g. all are to implement the same set of IDL interfaces) but the GPIO signals for two are different from those for the other three, the user can duplicate the original client specification and have one specification for the first two clients and the duplicate for the other three clients.
The compiler command line, using the original specification:
```txt
% idlv -client ctype 5 all [...]
```
The compiler command line, using a duplicate specification:
```batch
% idlv -client ctype1 2 all -client ctype2 3 all [...]
```
All clients will still implement the same set of IDL interfaces (in this case, all interfaces within the specified IDL files), but dividing the specification has produced separate GPIO records for each specification.
# 5.7.2 GPIO port entries
The GPIO VHDL records appear in the port lists for clients, servers and TLE.
For clients and servers, the port names are user\_out (for the output record) and user\_in (for the input record).
For the TLE, the port names match the client or server instance names together with an ‘\_in’ or ‘\_out’ suffix.
Example:
```batch
% idlv test.idl -client cbase 2 all -server sbase 1 all
```
The compiler command line above produces the following GPIO signals in the TLE:
```vhdl
-- User I/O signals for bus object cbase_0.
cbase_0_in : in cbase_in_type;
cbase_0_out : out cbase_out_type;
-- User I/O signals for bus object cbase_1.
cbase_1_in : in cbase_in_type;
cbase_1_out : out cbase_out_type;
-- User I/O signals for bus object sbase.
sbase_in : in sbase_in_type;
sbase_out : out sbase_out_type
```
# 5.8 The Perfect Hash Generator Utility
The Perfect Hash Generator (PHG) utility generates a VHDL entity that provides hash mapping functionality. The user supplies the lists of strings and mapping values, and the PHG produces an entity that maps the CRC-16 hashes of the names to the mapping values. The PHG (and the generated process) use the the CRC-16 hasher component from ICO. When performing the hashing of the names, the names are given an explicit null terminator (zero octet) and then padded to a length that is a multiple of 4 bytes with additional nulls.
Figure 7 Perfect Hash Timing
The generated hasher is intended to be used within servants or clients and takes a 32-bit word input via the data\_in signal when the data\_rd signal is high. Two clock cycles after the last word is written to the hasher the data\_valid signal goes high if the string matches and the data\_out signal will be the matching value.
To run the PHG, use the phg script or phg.bat batch file. Running without parameters (or with a first parameter of -help) will display brief usage information as follows:
```txt
% phg -help
Usage: phg <entity_name> <output_width> { <name> <value> }
entity_name : the name of the generated VHDL entity
output_width : the width (in bits) of the mapped values
name / value : the name and value (in decimal) for a mapping
```
The SCA simulation example demonstrates the use of the PHG utility. The server\_resource server implements the PortSupplier interface, and a hasher is used to map between strings containing the port names and numeric identifiers. The hasher entity is generated using the following command:
```txt
% phg sca_hash 4 alpha 0 beta 1 gamma 2 theta 3 frequency 4 power 5
```
This produces a hasher entity called sca\_hash, with an output bit width of 4, mapping between the six specified pairs of names and values. The hasher is instantiated by the test bench and connected to server\_resource via the GPIO records.
# 5.9 ICO Development Lifecycle
The ICO development lifecycle is typically divided into a number of phases, as shown in Figure 8 and described more fully in the following sections.
Figure 8 ICO Development Lifecycle
# 5.9.1 Create the IDL
The first step is to define the IDL entities that you wish to use within the system. The compiler will generate VHDL code according to the mapping specification— client and server entities and a top-level entity, which the developer then edits as required. For more information please refer to Chapter 3 of the OMG CORBA specification, ‘IDL Syntax and Semantics’.
An example of an IDL definition for a servant which receives a 32-bit number and increments it by one.
```txt
module TestModule
{
interface TestServer
{
long incrementByOne (in long value);
};
};
```
# 5.9.2 Compile the IDL
The compilation of the IDL is achieved by the IDL to VHDL compiler provided with ICO.
# 5.9.3 Integrate User Logic
In the example IDL above the incrementByOne operation sends a single long value to the servant and returns an incremented long value. The operation name differentiates between operations and allows the servant to direct the input parameters to their correct destination.
The sequence and timing of how and when data is sent and received by the bus is critical to the correct operation of ICO. The IDL to VHDL compiler provides the user with a VHDL file providing pre-built state machines that handle reads and writes to and from the bus. The following figures (Figure 9 on page 52 and Figure 10 on page 53) show the conceptual Finite State Machine (FSM) for both the client and servant for the example IDL.
Figure 9 Servant Finite State Machine
Figure 10 Client Finite State Machine
For the servant case the FSM idle state is request\_state. It will remain in this state until the servant has received all of the request data sent to it by a client and it has been granted access to the bus. The FSM will then proceed to go through all of the reply states required to send data on the bus. Once the reply is complete, the servant’s FSM returns to request\_state.
It is the user’s responsibility to provide the data to the servant when the state relevant to that piece of data is reached. This can be done by editing procedures that are generated by the IDL compiler. The state machine code uses these procedures to obtain the required data. The file containing the procedures is the only file that user needs to modify.
A special procedure named idle\_action is generated for clients. This procedure is used to initiate the sequences of states that produce a request. The enumeration action is set to the appropriate value to start a request.
Writes to the servant arbitration granting access to the bus are illustrated by the timing diagram in Figure 11 on page 54.
The busy line is asserted high to indicate that this servant is now busy and subsequently unable to handle any more requests. The receiving bridge addresses the servant via the adr\_i (address bus in), dat\_i (data bus in) and write\_i.
Figure 11 Bus To Servant Write
One data word is transferred per clock cycle. The data may be written in contiguous cycles or the write\_i signal may go low for one or more clock cycles (see Figure 12).
Figure 12 Bus Write Timing
The generated code also controls the bus\_request signal to request access to the bus and the state machine progresses through the reply states only when the bus\_grant signal is high. Note that this bus arbitration occurs on both the input bus and output buses.
Once all the data has been sent the bus must be released to allow other bridges, servants or clients to access the bus. This occurs when the busy line drops low together with the bus\_request and bus\_grant lines. The bus arbitration scheme will then release the bus and allow another message to enter the servant. It is important to note that in the case of multiple clients and servants there are logically two buses, one for incoming data and one for outgoing data. This means that once a servant has finished receiving data it will not block other servants or clients.
Figure 13 Servant To Bus Write
# 5.9.4 Obtaining the ICO servant IOR
CORBA uses Interoperable Object References (IORs) to identify individual servants. The IOR will contain one or more profiles with each profile providing endpoint information for a particular form of transport as well as object key data.
Since ICO is designed to be used with a user specified transport the IDL compiler can only supply the object key part of an IOR. The IDL compiler generates an initial\_references.txt file that contains partial IORs in the form of ‘corbalocs’. A corbaloc is an IOR in a readable string form and consists of a corbaloc prefix, endpoint information and the object key encoded as a string1 . The generated text file will contain lines in the form:
```txt
-ORBInitRef server_demo=corbaloc:<PROTOCOL>:<ENDPOINT>/%01
```
The user must substitute the appropriate values for protocol, host and endpoint. These values will depend on the type and configuration of the transport connected to ICO. An ORB which supports the addition of transports (such as e\*ORB) will then be capable of using the above form of initial object references to connect to the ICO server.
Using non-standard (for CORBA) transports will require the appropriate transport extension to be implemented for the software ORB.
In circumstances where the corbaloc form cannot be used, such as passing the reference via a CORBA program that does understand the transport in use, then a ‘stringified’ IOR will be required. A stringified IOR contains a textual encoding of the binary form of the object reference. The corbaloc IOR can be converted to the stringified form using a small CORBA program that takes the corbaloc as input and prints the stringified IOR.
```c
#include "eOrbC/orb.h"
int main (int argc, char **argv)
{
CORBA_Environment ev;
```
1. Object key data is encoded using RFC 2396 escape convention.
```c
CORBA_Object obj;
CORBA_ORB orb;
char *str;
/* Install plugins */
EORB_IIOP_plugin();
if (argc != 2)
{
fprintf (stderr, "usage: convert corbaloc:\...\n");
return -1;
}
/* Initialize the ORB */
orb = CORBA_ORB_init (&argc, argv, "eorb-ce", &ev);
EORB_CHECK_EXC_RETURN_VAL ("CORBA_ORB_init", &ev, -1);
/* Resolve the server */
obj = CORBA_ORB_string_to_object (orb, argv[1], &ev);
EORB_CHECK_EXC_RETURN_VAL ("string_to_object", &ev, -1);
str = CORBA_ORB_object_to_string (orb, obj, &ev);
EORB_CHECK_EXC_RETURN_VAL ("object_to_string", &ev, -1);
printf ("ior = %s\n", str);
/* Clean up */
CORBA_string_free (str);
CORBA_Object_release (obj, &ev);
CORBA_ORB_destroy (orb, &ev);
return 0;
```
# 5.10 ICO Development Examples
The ICO distribution is supplied with a number of examples, which can be found in the examples directory. Two of these examples are described here.
# 5.10.1 Increment by One Example
This section uses the ‘increment by one’ simulation example to illustrate the steps needed to design, implement and simulate an ICO server. This example is installed in the examples/simulation/incbyone directory.
# 5.10.1.1 Design
The first step is to define the server’s operations in IDL. In this example we only need one operation that will take in a numeric value and return the incremented value. This example is in a file called incbyone.idl:
```txt
module TestModule
{
interface TestServer
{
long incrementByOne (in long n);
};
};
```
The server will be implemented in VHDL. It will store the result of adding one to the number passed during the request, and return the incremented value in the reply. The client will be implemented in C using e\*ORB and will issue requests from a GPP (e.g. the host PC).
# 5.10.1.2 Implementing The Server
Run the IDL compiler with the command line below. The compiler will use the example library for the generated code, which will be placed in the current directory. The only servant needed is a single instance of the server, and the compiler will generate a default receive/transmit bridge pair.
```batch
% idlv -library example -server incserver 1
TestModule::TestServer incbyone.idl
```
Alternatively, issue the following command to run the ICO IDL compiler as above and also generate the client executable:
```txt
% scons -u
```
To implement the servant, edit the generated incserver\_pkg.vhd file and add the required implementation logic. Since the result value needs to be stored, an appropriate entry needs to be added to the incby\_one\_register\_type record. Add the field:
```sql
result : CORBA_long;
```
Next change the constant incby\_one\_register\_init used as the reset state to reflect the change to the record definition by adding:
```txt
result => (others => '0')
```
The field result needs to be set when the value parameter is supplied. When the value is written to the servant the TestServer\_incrementByOne\_n procedure is invoked. The signal value will contain the n value. Record the incremented value in t h e u s e r s t a t e b y a d d i n g t h e f o l l o w i n g l i n e a s t h e b o d y o f t h e TestServer\_incrementByOne\_n procedure:
```javascript
v.result := value + 1;
```
Next, the incremented value needs to be returned in the server’s reply. The state m a c h i n e t h a t g e n e r a t e s t h e r e p l y w i l l i n v o k e t h e p r o c e d u r e TestServer\_incrementByOne\_return at the appropriate time. Complete the i m p l e m e n t a t i o n b y a d d i n g t h e f o l l o w i n g l i n e t h e b o d y o f t h e TestServer\_incrementByOne\_return procedure:
```javascript
result := r.result;
```
The completed package is shown below. Since this example contains no sequences or arrays, each operation (excluding default\_action) will be invoked exactly once and the operations will be invoked in the order that they appear in the source code.
```vhdl
package incserver_pkg is
type incserver_in_type is record
dummy: std_logic;
end record;
type incserver_out_type is record
dummy: std_logic;
end record;
constant incserver_out_init: incserver_out_type :=
(
dummy => '0'
);
type incserver_register_type is record
output: incserver_out_type;
result: corba_ulong;
end record;
constant incserver_register_init: incserver_register_type :=
(
output => incserver_out_init,
result => (others => '0')
);
-- procedure declarations removed for clarity
end package incserver_pkg;
package body incserver_pkg is
procedure default_action
(
r: incserver_register_type;
d: incserver_in_type;
variable v: inout incserver_register_type
) is
begin
end procedure default_action;
-- ::TestModule::TestServer::incrementByOne
procedure TestModule_TestServer_incrementByOne_request(
r: incserver_register_type;
d: incserver_in_type;
variable v: inout incserver_register_type
) is
begin
end procedure TestModule_TestServer_incrementByOne_request;
procedure TestModule_TestServer_incrementByOne_value
(
r: incserver_register_type;
d: incserver_in_type;
variable v: inout incserver_register_type;
value: corba_long
) is
begin
v.result := value + 1;
end procedure TestModule_TestServer_incrementByOne_value;
procedure TestModule_TestServer_incrementByOne_request_end
(
r: incserver_register_type;
d: incserver_in_type;
variable v: inout incserver_register_type
```
```vhdl
) is
begin
end procedure TestModule_TestServer_incrementByOne_request_end;
procedure TestModule_TestServer_incrementByOne_return
(
r: incserver_register_type;
d: incserver_in_type;
variable v: inout incserver_register_type;
variable ready: inout boolean;
variable value: out corba_long
) is
begin
value := r.result;
end procedure TestModule_TestServer_incrementByOne_return;
end incserver_pkg;
```
# 5.10.1.3 Implementing the Client
The client is implemented in C and built using e\*ORB. It initialises the ORB instance, obtains a reference to the server via an initial reference set up on the command line, performs the call to the server, reports the results, and cleans up.
Please refer to the e\*ORB C User Guide for use of e\*ORB on your host platform.
An SCons build file is provided; to build the client executable, enter ‘scons -u’ in the incbyone directory.
# 5.10.1.4 Simulation
To run this example under simulation, start ModelSim with the following command:
```batch
% vsim -do "build.do"
```
The script will compile all the required code, start a simulation with the top\_devboard\_tb entity, set up the waveform window, run by 10ns to move past the test bench reset and start the tb\_server process defined in the server.tcl file.
With the server running, start the client and perform the call to the server. The client r e s o l v e s t o t h e s e r v e r u s i n g t h e i n i t i a l r e f e r e n c e ‘ i c o ’ . T h e object\_keys\_pkg.vhd file shows that the compiler has allocated object key 1 to the server. Launch the client with the following command from the incbyone directory, replacing ‘modelsim\_host’ with the appropriate host name:
# Linux
On Linux systems:
```txt
% client -ORBInitRef ico=corbaloc:iiop:modelsim_host:9001/%01
```
# WIN
On Windows systems:
```txt
% client.exe -ORBInitRef ico=corbaloc:iiop:modelsim_host:9001/%01
```
The client will initialise the ORB, resolve to the server and perform the call.
# 5.10.2 LEDs Example
The following example shows how to implement a simple output interface driving a set of LEDs on a Altera Cyclone III development board. The completed example can be found in the examples/synthesis/cyclone\_III\_leds directory. The IDL used is shown below:
```txt
module Demo
{
interface DevBoard
{
oneway void leds (in octet value);
};
};
```
Compile the IDL with ICO compiler:
```batch
% idlv -server leds 1 Demo::DevBoard Demo.idl
```
The next step is to define the output signals. Edit the leds\_pkg.vhd file and replace the dummy field in leds\_out\_type with:
```txt
leds: std_logic_vector(7 downto 0);
```
The leds\_in\_type and leds\_register\_type records are not used in this example and are not modified. The constant leds\_out\_init must be adjusted to reflect the change to leds\_in\_type by replacing the dummy initialisation with:
```txt
leds => (others => '0');
```
Next the output is set to the inverse of the supplied octet value (as the FPGA signals are connected to the LED cathodes). A line assigning to the output variable has been added to the DevBoard\_value\_in procedure:
```vhdl
procedure DevBoard_leds_value_in
(
r: leds_register_type;
d: leds_in_type;
variable v: inout leds_register_type;
value : corba_octet
) is
begin
v.output.leds := not std_logic_vector(value);
end procedure DevBoard_leds_value_in;
```
This procedure will be invoked at the point that the value parameter is recieved by the servant. The top\_devboard.vhd file connects the ouput signals from the servant to the LEDs using the signal provided by the generated ico\_tle component.
```txt
signal leds_out : leds_out_type;
tle : ico_tle
port map
(
reset_n => reset,
```
```txt
clk => clk,
transport_in => trans_in,
transport_out => trans_out,
leds_in => (others => '0'),
leds_out => leds_out
);
user_led <= leds_out.leds;
```
# 5.11 Generating Sequences
When a servant or client produces a sequence as an output (out parameter or return for a servant, in parameter for client) then the user code must specify the length of the sequence. ICO generates skeleton code with defined constants for each output sequence. If a fixed-size sequence is required then the user can set the value of the corresponding constant to the correct value (the default sequence length is zero, giving an empty sequence).
If a variable sequence length is required (for example the required length is set by a previous operation) then the length can be recorded in a register and the register used in place of the sequence length constant. The constants are passed as the second argument to a start\_sequence procedure call and are required to be of type corba\_ulong.
The example found in examples/simulation/twoway\_sequence illustrates generating variable length sequences. The example interface includes a setup operation that sets the length of sequence required and a receive operation that returns a sequence.
```c
module SequenceDemo
{
interface Transfer
{
typedef sequence <octet> OctetSeq;
void setup (in unsigned long size);
octet send (in OctetSeq data);
void receive (out OctetSeq data);
octet swap (inout OctetSeq data);
};
interface Config
{
unsigned long getRegisterValue (in octet_regAddress);
void setRegisterValue (in octet_regAddress, in unsigned long regValue);
};
};
```
A f i e l d l e n g t h o f t y p e c o r b a \_ u l o n g h a s b e e n a d d e d t o t h e transfer\_register\_type record in the transfer\_pkg (found in transfer\_pkg.vhd).
```rust
type transfer_register_type is record
output: transfer_out_type;
length: corba_ulong;
result: corba_octet;
end record;
```
The implementation of the setup operation sets the length field to incoming size parameter:
```vhdl
procedure SequenceDemo_Transfer_setup_size (
r: transfer_register_type;
d: transfer_in_type;
variable v: inout transfer_register_type;
value: corba_ulong
) is
begin
v.length := value;
end procedure SequenceDemo_Transfer_setup_size;
```
The SequenceDemo\_Transfer\_receive\_data\_out\_length procedure is used to supply the length the reply sequence.
```vhdl
procedure SequenceDemo_Transfer_receive_data_out_length (
r: transfer_register_type;
d: transfer_in_type;
variable v: inout transfer_register_type;
variable ready: inout boolean;
variable value: out corba_ulong
) is
begin
value := r.length;
end procedure SequenceDemo_Transfer_receive_data_out_length;
```
The procedure SequenceDemo\_Transfer\_receive\_data\_out will then be invoked zero or more times depending upon the value in r.length. Note that in this example an octet sequence is being generated, therefore four octets are written for each invocation.
# 5.12 Using the CORBA Any Type
ICO can receive and send parameters of type Any. The value contained in the Any must be a primitive value or string (see Section 4.2.8, Any Mapping, on page 32). When an Any parameter is used a range of addresses are allocated to the parameter with separate addresses for each type that could contained in the Any. When receiving an Any parameter the address (or addresses) corresponding to the type contained in the Any will be used and the data contained in the Any placed on the data bus. The generated VHDL code will contain case statements for each of the possible types for an Any parameter. When sending an Any parameter the same process is followed with the data to be contained in the Any written to the data bus using an address corresponding to the type of the data.
The example found in examples/simulation/sca illustrates sending and receiving Any parameters. The file resource\_pkg.vhd implements a configure operation that receives as a parameter a sequence of DataType structures and a query operation that both receives and sends sequences of DataType. The DataType structure has a field value of type Any. The following IDL excerpt shows the definition of the operations and types:
```txt
module CF {
struct DataType {
```
```cpp
string id;
any value;
};
typedef sequence <DataType> Properties;
interface PropertySet {
void configure (in CF::Properties configProperties)
raises (PropertySet::InvalidConfiguration,
PropertySet::PartialConfipropertySet::PartialConfiguration);
void query (inout CF::Properties configProperties)
raises (UnknownProperties);
}
```
The implementation of the configure operation is only interested in two of the potentially contained types. In each case it records the value in a register for later use. For example the code that handles a unsigned long value field is:
```vhdl
procedure CF_PropertySet_configure_configProperties_value_ulong
(
r: resource_register_type;
d: resource_in_type;
variable v: inout resource_register_type;
value: corba_ulong
) is
begin
v.ulong_value := value;
end procedure
CF_PropertySet_configure_configProperties_value_ulong;
```
The implementation of the query operation sends Anys containing unsigned short and unsigned long values:
```vhdl
procedure CF_PropertySet_query_configProperties_out_value_ushort
(
r: resource_register_type;
d: resource_in_type;
variable v: inout resource_register_type;
variable ready: inout boolean;
variable value: out corba_ushort
) is
begin
value := corba_ushort(r.output.power);
end procedure
CF_PropertySet_query_configProperties_out_value_ushort;
procedure CF_PropertySet_query_configProperties_out_value_ulong
(
r: resource_register_type;
d: resource_in_type;
variable v: inout resource_register_type;
variable ready: inout boolean;
variable value: out corba_ulong
) is
begin
value := corba_ulong(r.output.frequency);
v.require_freq := '0';
end procedure
CF_PropertySet_query_configProperties_out_value_ulong;
```
S e l e c t i o n o f t h e a p p r o p r i a t e s t a t e i s p e r f o r m e d b y t h e CF\_PropertySet\_query\_configProperties\_out\_value procedure.
```txt
procedure CF_PropertySet_query_configProperties_out_value (
r: resource_register_type;
d: resource_in_type;
variable v: inout resource_register_type;
variable ready: inout boolean;
variable any_type: out corba_any_type
) is
begin
if r.require_freq = '1' then
any_type := any_ulong;
else
any_type := any_ushort;
end if;
end procedure CF_PropertySet_query_configProperties_out_value;
```
# TRANSPORTS
# CHAPTER
# Transports
# 6.1 Introduction
When we talk about a transport within the context of ICO, we are referring to the protocol component such as TCP, UDP, Ethernet, RapidIO or PCIe, as opposed to the electrical standard.
An ICO transport refers to the interface that ICO uses to receive and transmit data together with the layout of the data as defined by the transport protocol. In order for ICO to effectively interact with a desired transport, the transport is required to deliver the data payload carried by it in either a streaming or packeted format.
After a message has been received, properly aligned and decoded by the transport it is passed on to an ICO receive (Rx) bridge using a simple FIFO interface as shown in Figure 14 on page 68. In this diagram there are three transports indicated by the colours yellow, green and red. The different colours signify either a number of electrical connections to different transports or a number of different physical connections to a single transport.
Each transport connection (red, yellow or green) has a set of connection identifiers which are passed to ICO at the start of any GIOP message that differentiates protocol connections.
For example, if we process a received PCIe TLP packet we need to extract from the header the address and ID of the sender and store it in order to be able to reply to a CORBA request.
This address and ID are associated with a unique key which relates to this transport and in the case of connection orientated transports the connection as well. This key is then passed up to ICO as a Connection Id (CID) and used on the transmit of a GIOP message to indicate which transport and what connection the message should go to.
The ideas above are expanded upon in the following sections.
# 6.2 Transport Connections
Figure 14 Connections in ICO
Figure 14 above shows how a connection is made to ICO. A receive bridge may have a corresponding transmit bridge and serve as a bridge between the transport and the CORBA world. The receive bridge translates messages from the outside world from the GIOP v1.0 format to the BIOP protocol.
The bridges are designed to consume data as quickly as possible together with providing as little push-back as possible, given the arbitration scheme chosen and the number of transports involved.
Each receive bridge is connected to the same arbitration block which controls access to the input bus that feeds servants and clients. In turn every servant and client is connected to an outgoing transmit arbitration block which controls access to the output bus. The separation between input and output buses allows full duplex communication to occur such as a servant receiving a message while another servant or client is sending one. This in turn increases the bandwidth of ICO and minimises bus contention.
ICO has one interface for receiving messages and one interface for transmitting messages per receive/transmit bridge pair. The messages transferred on both transmit and receive interfaces are in GIOP format and should be treated by lower level blocks as raw non-encapsulated data.
The part of the TLE entity definition relevant to the bridges is shown below. By design, the bridges closely resemble a set of FIFO interfaces with 32-bit data ports. The TLE is using the default pair of bridges and connection support and object keys are both enabled. The databus and ConnectionID subtypes are defined in the ico bus package, and are 32 bits and 8 bits wide respectively. The key\_index\_type subtype is defined in the output\_engine\_pkg package and is 8 bits wide.
```vhdl
entity ico_tle is
generic
(
transport_config : transport_config_type := (2, 5, 12)
);
port
(
reset_n : in std_logic;
clk : in std_logic;
-- Signals for transport.
transport_out : in transport_out_type;
transport_in : out transport_in_type;
...
);
end ico_tle;
```
Each transport is represented by a pair of signal records. The records are:
```vhdl
type transport_in_type is record
data : slv32;
valid : std_logic;
full : std_logic;
id : ConnectionID;
end record;
type transport_out_type is record
data : slv32;
wr : std_logic;
rd : std_logic;
id : ConnectionID;
end record;
```
Table 8 Transport Interface Description
| Signal Name | I/O | Description | Optional |
| reset_n | I | Reset signal. This signal is active low and asynchronous. | No |
| clk | I | Clock signal. | No |
| transport_out.id | I | Connection Id. 8 bits. | No |
| transport_out.data | I | Transport data in. 32 bits. | No |
| transport_out.wr | I | Transport data input write. Indicates ipb_fifo_in_data is valid. | No |
| transport_in.full | O | Input FIFO full indicator. Asserted when the remaining space in the FIFO is at or below the value specified by the ipb_fifo_in_low generic parameter. | No |
| transport_in.id | O | Connection Identifier. 8 bits.Set to zero if not needed. | No |
| key_index | O | Index of object key word. 8 bits. | Yes |
| key_data | I | Object key data. 32 bits. | Yes |
| transport_in.wr | O | Asserted when transport output data is valid. | No |
| transport_in.data | O | Transport output data. 32 bits. | No |
| transport_out.rd | I | Transport output data read signal.Asserted when the transport is ready to accept data. When de-asserted there will be up to a 4 cycle delay before data transmission is ceased. | No |
Table 9 Transport Generics Description