source: rtems/tools/cpu/nios2/README @ 5f5f681

$Id$

nios2gen:
  Tool to generate BSP data for boards utilizing NIOS2 soft core processor.

=================================
What it does

It creates a sopc.h and linkcmds file for RTEMS nios2 BSPs from one or more inputs:

1. SOPC System Description PTF

As an output from SOPC Builder you get a file with extension ".ptf" that fully
describes the SOPC, including all CPUs, memory and integrated peripherals.
(PTF simply means "plain-text file").

2. BSP Configuration PTF

This file, using the same format as the SOPC System Description PTF, describes
which components of the SOPC shall be used by the BSP. For example, there may
be several timers, but a BSP wants at least one named "CLOCK" and optionally
another named "TIMER". This mapping can be specified in the BSP.

=================================
Contents of the configuration PTF

There can be definitions of ...

HEADER: This is written to sopc.h before anything else. Example:

  HEADER = "
  #ifndef __SOPC_H
  #define __SOPC_H 1
  ";

EPILOG: This is written to sopc.h after anything else. Example:

  EPILOG = "
  #endif
  ";

CLOCKS section: Used to specify names for clocks to be used in definitions in 
the sopc.h. The default name (if none is specified here) is the uppercased name
as in the system description PTF. Specify the name you want on the left, the
name in the sopc PTF on the right! Example:

  CLOCKS
  {
    GLOBAL_CLOCK = "sys_clk";
  }

MODULES section: Same as clocks but for modules / peripherals. As a special definition,
if the PTF contains more than one nios2 CPU, it /must/ define a CPU to use. Example to
select cpu_0 and rename timer_0 to CLOCK and timer_1 to TIMER:

  MODULES
  {
    CPU = "cpu_0";
    CLOCK = "timer_0";
    TIMER = "timer_1";
  }

CLASS xyz sections: These specify what you want in the sopc.h, and how the definitions
shall be named. Actually, the CLASS xyz should look exactly like the corresponding MODULE
specification in the system description PTF of modules belonging to that class; e.g. a
a JTAG UART is originally described like this:

   MODULE jtag_uart_0
   {
      class = "altera_avalon_jtag_uart";
      class_version = "1.0";
      iss_model_name = "altera_avalon_jtag_uart";
      SLAVE avalon_jtag_slave
      {
         SYSTEM_BUILDER_INFO
         {
            Bus_Type = "avalon";
            Is_Printable_Device = "1";
            Address_Alignment = "native";
            Address_Width = "1";
            Data_Width = "32";
            Has_IRQ = "1";
            Read_Wait_States = "peripheral_controlled";
            Write_Wait_States = "peripheral_controlled";
            JTAG_Hub_Base_Id = "0x04006E";
            JTAG_Hub_Instance_Id = "0";
            MASTERED_BY cpu_0/data_master
            {
               priority = "1";
            }
            IRQ_MASTER cpu_0/data_master
            {
               IRQ_Number = "2";
            }
            Base_Address = "0x08000000";
         }
      }
      ...
   } 

If you want to have definitions about its base address and irq number in your sopc.h,
define a CLASS for altera_avalon_jtag_uart that matches the MODULE description above,
but instead of values for the items you specify names to be used in your sopc.h (You
can omit items from the MODULE as you like, but the section nesting must match; and
section names (such as avalon_jtag_slave for the SLAVE section) also have to match)

   CLASS altera_avalon_jtag_uart
   {
       SLAVE avalon_jtag_slave
       {
           SYSTEM_BUILDER_INFO
           {
               Base_Address = "BASE_ADDR";
               IRQ_MASTER { IRQ_Number = "IRQ"; }
           }
       }
   }

The output for jtag_uart_0 will be:

   #define JTAG_UART_BASE_ADDR 0x021208D0
   #define JTAG_UART_IRQ 1

There are some values with special meaning to nios2gen,

N2G_CLOCKREF_CLOCK: This should be used whereever the value in the SOPC PTF
specifies the name of a clock. nios2gen will use whatever you  configured for
the selected clock in your CLOCKS section.

N2G_CLOCKREF_DEVICE: This should be used whereever the value in the SOPC PTF
specifies the name of a module. nios2gen will use whatever you  configured for
the selected module in your MODULES section.

Additionally, you can specify items in your CLASSes so that nios2gen will include
constant definitions in the sopc.h whenever such CLASS is present. The format is

  N2G_DEFINE_xyz = "123"

and will result in 

#define MODULENAME_xyz 123