Jump to: navigation, search

Difference between revisions of "DSDP/RTSC - xdc.platform.ICpuDataSheet"

m
m (Sketch)
 
(17 intermediate revisions by 3 users not shown)
Line 5: Line 5:
 
The current RTSC platform model contains a description of the hardware (HW) as a part of the configuration model.&nbsp; This part of the model - accessible via Program.cpu - allows portable XDCscript code to reflect on the specific HW and conditionally generate results that are platform-specific.<br>  
 
The current RTSC platform model contains a description of the hardware (HW) as a part of the configuration model.&nbsp; This part of the model - accessible via Program.cpu - allows portable XDCscript code to reflect on the specific HW and conditionally generate results that are platform-specific.<br>  
  
Although the current HW model provides specific device information and a complete memory map as seen by executing applications, it does not currently provide a way to identify peripherals that are part of the device; e.g., what types of peripherals (timers, serial ports, ADCs, etc.) are present, how many exist, their base addresses, and any device specific attributes associated with these peripherals).<br>
+
Although the current HW model provides specific device information and a complete memory map as seen by executing applications, it does not currently provide a way to identify peripherals that are part of the device; e.g., what types of peripherals (timers, serial ports, ADCs, etc.) are present, how many exist, their base addresses, and any device specific attributes associated with these peripherals).<br>  
  
 
== Goals  ==
 
== Goals  ==
Line 11: Line 11:
 
Extend the platform model to include a notion of a "peripheral" and augment the existing platform packages to include sufficient information to enable "automatic" configuration of peripheral drivers.&nbsp; Automatic configuration implies:<br>  
 
Extend the platform model to include a notion of a "peripheral" and augment the existing platform packages to include sufficient information to enable "automatic" configuration of peripheral drivers.&nbsp; Automatic configuration implies:<br>  
  
*user rarely needs to add configuration statements that are device specific  
+
*user rarely needs to add device specific configuration statements<br>
*peripheral drivers can get information from the platform model (that is "implied" by the HW platform) sufficient to ensure all software drivers operate properly without conflict
+
*peripheral drivers can get information from the platform model (that is "implied" by the HW platform) sufficient to eliminate the need for internal tables of specific devices<br>
 +
*the ability to detect conflicting/overlapping "ownership" of peripherals by separate runtime packages ensuring all software drivers operate properly without conflict
  
 
== Requirements  ==
 
== Requirements  ==
Line 21: Line 22:
 
*<tt>ti.sdo.ipc.Sem</tt><br><br>
 
*<tt>ti.sdo.ipc.Sem</tt><br><br>
  
== Sketch<br> ==
+
== Example ==
  
The following notes sketch the current thinking.<br>
+
PSP drivers maintain this monster table which is referenced in the Mod.xs files. All this information probably belongs in the catalog.  
  
ICpuDataSheet would include a map of peripherals, say&nbsp;xdc.platform.IPlatform.Peripheral, were each peripheral would be a structure containing a name, base address, and an arbitrary hash of device specific attributes. <br>
+
Here is an example from <tt>Uart.xs</tt> ([[Media:Soc.zip|Soc.zip]] - soc.xs)
 +
<pre>var soc = xdc.loadCapsule("ti/psp/cslr/soc.xs");
  
*name would name a RTSC module that identifies the HW peripheral
+
/*
*the base address would be a device
+
* ======== module$use ========
*the attrs hash would contain attributes such as interrupt id
+
*/
 +
function module$use()
 +
{
 +
    Uart = this;
 +
    IDriver = xdc.module("ti.sdo.io.IDriver");
 +
    DriverTypes = xdc.useModule("ti.sdo.io.DriverTypes");
 +
    Semaphore = xdc.useModule("ti.sysbios.ipc.Semaphore");
 +
       
 +
    if (!(Program.cpu.deviceName in soc.deviceTable)) {
  
The keys of the peripheral map might be the device-specific names for the peripherials.
+
        Uart.$logError("Unsupported device",this, Program.cpu.deviceName);
 +
    }
 +
    else {
 +
        var uarts = soc.deviceTable[Program.cpu.deviceName].uarts;
 +
                 
 +
        Uart.numInstances = uarts.length;
 +
        Uart.defaultDeviceInfo.length = uarts.length;
  
 +
        for (var i = 0; i &lt; Uart.numInstances; i++) { 
 +
            Uart.defaultDeviceInfo[i].baseAddress = uarts[i].baseAddress;
 +
            Uart.defaultDeviceInfo[i].cpuEventNumber = uarts[i].cpuEventNumber;
 +
            Uart.defaultDeviceInfo[i].rxDmaEventNumber = uarts[i].rxDmaEventNumber;
 +
            Uart.defaultDeviceInfo[i].txDmaEventNumber = uarts[i].txDmaEventNumber;
 +
            Uart.defaultDeviceInfo[i].inputFrequency =  uarts[i].inputFrequency;
 +
        }
 +
    }
 +
}
 +
</pre>
 +
== Sketch<br>  ==
 +
 +
The following notes sketch the current thinking.<br>
 +
 +
ICpuDataSheet would include a map of peripherals, say&nbsp;xdc.platform.IPlatform.Peripheral, were each peripheral would be an instance of a module that inherits IPeripheral interface. The interface would contain only a name, base address, and an interrupt number. Inheriting modules would add device specific config parameters. <br>
 +
 +
*name would be a name of a RTSC module that identifies the HW peripheral
 +
*the base address would be a device specific address of the block of addresses for the peripheral's registers
 +
*interrupt id
 +
*an instance of the named module (what was the purpose of this?)
 +
 +
The keys of the peripheral map might be the device-specific names for the peripherals.
 +
 +
Since each peripheral is an instance of a module, it can maintain "ownership" information and enforce the constraint that only one package may claim control of the peripheral.&nbsp; This will prevent applications from trying to use HW already managed by high-level packages.
 +
 +
The most general peripheral interface would look like this:
 +
{{codeblock|
 +
    metaonly interface IPeripheral {
 +
      instance:
 +
        config string name; // "Timer", "Cache", "Interrupts" or a more specific name - "TimerA3"
 +
        config UInt baseAddr;
 +
        config IPeripheralAttrs attrs;
 +
    }
 +
}}
 +
 +
The attributes for each peripheral would inherit from IPeripheralAttrs:
 +
 +
{{codeblock|
 +
    metaonly module InterruptsAttrs inherits IPeripheralAttrs {
 +
        config UInt intNum;
 +
    }
 +
}}
 +
 +
=== Peripheral Identification ===
 +
 +
How do we specify something as "Timer" or "Clock"?
 +
* We could require that the config <tt>name</tt> belongs to an enumerated type with constants TIMER, CLOCK, etc, but then that parameter couldn't be a string anymore.
 +
* We could define <tt>ITimer</tt>, <tt>IClock</tt> and other interfaces in <tt>xdc.platform.peripherals</tt>, which would be inherited by modules implementing the actual peripherals.
 +
* We could offer functions <tt>getTimers()</tt>, <tt>getClocks</tt> to be invoked by the users. That would restrict the list of peripherals that can be used to only the ones we explicitly named.
 +
 +
However, does a package that configures peripherals really care if there is some generic timer on the device? They may just need to know if there is "TimerA" or "TimerB" on the device?
 +
 +
The config parameter <tt>Program.cpu.attrs.peripherals</tt> would be defined as:
 +
{{codeblock|config IPeripheral.Instance peripherals[string]}}
 +
The device-specific peripheral names would be used as keys.
 +
 +
Do we need any functions (<tt>Program.cpu.attrs.getPeripherals(some search params)</tt>?
 +
 +
The interface ILM3Sx9xx in ti.catalog.arm package defines timers using the following structure:
 +
{{codeblock|
 +
    struct Timer {
 +
    string name;
 +
        UInt baseAddr;
 +
        UInt intNum;
 +
    };
 +
}}
 +
 +
and then an array of such objects is defined in the interface:
 +
 +
{{codeblock|<pre>config Timer timers[4] = [...];</pre>}}
 +
 +
The users access the array through <tt>Program.cpu.attrs.$orig.timers</tt>. <tt>ICpuDataSheetInstance attrs</tt> already exposes some of the information provided by the datasheet for the device, so the peripherals could fit here as well.
 +
<tt>Program.cpu.attrs</tt> should be <tt>$orig</tt> already, so the users do not need to know about that detail. Then, we could have a map <tt>Program.cpu.attrs.peripherals</tt>.
 +
 +
== Further Considerations ==
 +
<tt>ICpuDataSheet</tt> currently exposes readonly parameters, such as data size and CPU core string, but also exposes memory map, which can be changed depending on the register settings passed with the platform creation parameters. This happens before the user's script runs, so the memory map is readonly. Then, there is a third set of parameters, which can be changed by user's scripts, for example which controller can suspend a timer. Do we need to formally separate these types of parameters?
 +
 +
The solution we implement for passing parameters from platforms to devices at the platform creation time could be related to choices made here.
  
  
 
== Resources  ==
 
== Resources  ==
  
[http://rtsc.eclipse.org/cdoc-tip/index.html#xdc/platform/package.html RTSC Platform Model Reference] - the reference API for the current platform model<br>
+
[http://rtsc.eclipse.org/cdoc-tip/index.html#xdc/platform/package.html RTSC Platform Model Reference] - the reference API for the current platform model<br>  
 +
 
 +
[[Media:Soc.zip|Soc.zip]] - full PSP example text
  
<br>
+
<br>  
  
 
<br>
 
<br>

Latest revision as of 14:29, 8 January 2010


Introduction

The current RTSC platform model contains a description of the hardware (HW) as a part of the configuration model.  This part of the model - accessible via Program.cpu - allows portable XDCscript code to reflect on the specific HW and conditionally generate results that are platform-specific.

Although the current HW model provides specific device information and a complete memory map as seen by executing applications, it does not currently provide a way to identify peripherals that are part of the device; e.g., what types of peripherals (timers, serial ports, ADCs, etc.) are present, how many exist, their base addresses, and any device specific attributes associated with these peripherals).

Goals

Extend the platform model to include a notion of a "peripheral" and augment the existing platform packages to include sufficient information to enable "automatic" configuration of peripheral drivers.  Automatic configuration implies:

  • user rarely needs to add device specific configuration statements
  • peripheral drivers can get information from the platform model (that is "implied" by the HW platform) sufficient to eliminate the need for internal tables of specific devices
  • the ability to detect conflicting/overlapping "ownership" of peripherals by separate runtime packages ensuring all software drivers operate properly without conflict

Requirements

Automatic configuration of

  • ti.sysbios timers and
  • ti.sdo.ipc.Sem

Example

PSP drivers maintain this monster table which is referenced in the Mod.xs files. All this information probably belongs in the catalog.

Here is an example from Uart.xs (Soc.zip - soc.xs)

var soc = xdc.loadCapsule("ti/psp/cslr/soc.xs");

/*
 *  ======== module$use ========
 */
function module$use()
{
    Uart = this;
    IDriver = xdc.module("ti.sdo.io.IDriver");
    DriverTypes = xdc.useModule("ti.sdo.io.DriverTypes");
    Semaphore = xdc.useModule("ti.sysbios.ipc.Semaphore");
        
    if (!(Program.cpu.deviceName in soc.deviceTable)) {

        Uart.$logError("Unsupported device",this, Program.cpu.deviceName);
    }
    else {
        var uarts = soc.deviceTable[Program.cpu.deviceName].uarts;
                   
        Uart.numInstances = uarts.length;
        Uart.defaultDeviceInfo.length = uarts.length;

        for (var i = 0; i < Uart.numInstances; i++) {   
            Uart.defaultDeviceInfo[i].baseAddress = uarts[i].baseAddress;
            Uart.defaultDeviceInfo[i].cpuEventNumber = uarts[i].cpuEventNumber;
            Uart.defaultDeviceInfo[i].rxDmaEventNumber = uarts[i].rxDmaEventNumber;
            Uart.defaultDeviceInfo[i].txDmaEventNumber = uarts[i].txDmaEventNumber;
            Uart.defaultDeviceInfo[i].inputFrequency =  uarts[i].inputFrequency;
        }
    }
}

Sketch

The following notes sketch the current thinking.

ICpuDataSheet would include a map of peripherals, say xdc.platform.IPlatform.Peripheral, were each peripheral would be an instance of a module that inherits IPeripheral interface. The interface would contain only a name, base address, and an interrupt number. Inheriting modules would add device specific config parameters.

  • name would be a name of a RTSC module that identifies the HW peripheral
  • the base address would be a device specific address of the block of addresses for the peripheral's registers
  • interrupt id
  • an instance of the named module (what was the purpose of this?)

The keys of the peripheral map might be the device-specific names for the peripherals.

Since each peripheral is an instance of a module, it can maintain "ownership" information and enforce the constraint that only one package may claim control of the peripheral.  This will prevent applications from trying to use HW already managed by high-level packages.

The most general peripheral interface would look like this:

   metaonly interface IPeripheral {
     instance:
       config string name; // "Timer", "Cache", "Interrupts" or a more specific name - "TimerA3"
       config UInt baseAddr;
       config IPeripheralAttrs attrs;
   }

The attributes for each peripheral would inherit from IPeripheralAttrs:

   metaonly module InterruptsAttrs inherits IPeripheralAttrs {
       config UInt intNum;
   }

Peripheral Identification

How do we specify something as "Timer" or "Clock"?

  • We could require that the config name belongs to an enumerated type with constants TIMER, CLOCK, etc, but then that parameter couldn't be a string anymore.
  • We could define ITimer, IClock and other interfaces in xdc.platform.peripherals, which would be inherited by modules implementing the actual peripherals.
  • We could offer functions getTimers(), getClocks to be invoked by the users. That would restrict the list of peripherals that can be used to only the ones we explicitly named.

However, does a package that configures peripherals really care if there is some generic timer on the device? They may just need to know if there is "TimerA" or "TimerB" on the device?

The config parameter Program.cpu.attrs.peripherals would be defined as:

config IPeripheral.Instance peripherals[string]

The device-specific peripheral names would be used as keys.

Do we need any functions (Program.cpu.attrs.getPeripherals(some search params)?

The interface ILM3Sx9xx in ti.catalog.arm package defines timers using the following structure:

   struct Timer {
   	string	name;
       UInt	baseAddr;
       UInt	intNum;
   };

and then an array of such objects is defined in the interface:

config Timer timers[4] = [...];

The users access the array through Program.cpu.attrs.$orig.timers. ICpuDataSheetInstance attrs already exposes some of the information provided by the datasheet for the device, so the peripherals could fit here as well. Program.cpu.attrs should be $orig already, so the users do not need to know about that detail. Then, we could have a map Program.cpu.attrs.peripherals.

Further Considerations

ICpuDataSheet currently exposes readonly parameters, such as data size and CPU core string, but also exposes memory map, which can be changed depending on the register settings passed with the platform creation parameters. This happens before the user's script runs, so the memory map is readonly. Then, there is a third set of parameters, which can be changed by user's scripts, for example which controller can suspend a timer. Do we need to formally separate these types of parameters?

The solution we implement for passing parameters from platforms to devices at the platform creation time could be related to choices made here.


Resources

RTSC Platform Model Reference - the reference API for the current platform model

Soc.zip - full PSP example text