Changes between Initial Version and Version 1 of Component/Vci Target Fsm

Timestamp:

Mar 7, 2008, 5:51:38 PM (16 years ago)

Author:

Nicolas Pouillon

Comment:

--

Component/Vci Target Fsm

@@ +1 @@
+[wiki:Component SocLib Components General Index] 
+
+= Component description =
+
+This component is a caba utility component.
+This is a class which
+ * will handle most of the simple cases of VCI targets
+ * may handle many segments with different address ranges
+ * handle atomic operations for you
+ * will let you define the behaviour through callbacks
+
+It has a few template parameters:
+ * VCI parameters, the standart ones
+ * `default_target`: Whether it will send back an error response if the component is not authoritative for received address
+ * `support_llsc`: Wheter atomic operations should be supported.
+
+It has a few instance parameters:
+ * VCI target port to handle
+ * List of segments to handle, in the same form that the return value from `getSegmentList()` in the [wiki:Component/MappingTable MappingTable]
+ * fifo size, the amount of VCI words that may be served in a pipeline fashion
+  * setting to 1 means only one vci request word will be handled at a time, there will be no pipelining
+  * setting to more than 1 will enable pipelining
+
+If default target, this component filters the requests and directly returns an error if address is out of handled segments.
+
+If atomic operations are enabled, this component filters atomic operations and calls on_write callback only if atomic write is successful.
+
+= Component usage =
+
+Let's suppose we implement a VCI target component `MyComponent`.
+
+Let's have a target VCI port and a FSM handler.
+
+Let's also have two callbacks for read and write behaviour:
+
+{{{
+template<typename vci_param>
+class MyComponent
+    : soclib::caba::BaseModule
+{
+    // Import some definitions from vci_param
+    typedef typename vci_param::addr_t vci_addr_t;
+    typedef typename vci_param::data_t vci_data_t;
+
+    sc_in<bool> p_resetn;
+    sc_in<bool> p_clk;
+    soclib::caba::VciTarget<vci_param> p_vci;
+    soclib::caba::VciTargetFsm<vci_param> m_vci_fsm;
+
+    // Callbacks, see below for parameters' meanings
+    bool on_write( size_t seg, vci_addr_t addr, vci_data_t data, int be);
+    bool on_read( size_t seg, vci_addr_t addr, vci_data_t &data );
+
+    void transition();
+    void genMoore();
+
+    ...
+
+public:
+    MyComponent(
+        sc_module_name name,
+        const soclib::common::MappingTable &mt,
+        const soclib::common::IntTab &ident );
+};
+}}}
+
+== Initialization ==
+
+In the constructor, we must initialize the target fsm and its callbacks:
+
+{{{
+template <typename vci_param>
+MyComponent<vci_param>::MyComponent(
+    sc_module_name name,
+    const soclib::common::MappingTable &mt,
+    const soclib::common::IntTab &ident )
+    : p_resetn("resetn"),
+      p_clk("clk"),
+      p_vci("vci"),       // Constructor for the vci port, give it a name
+      m_vci_fsm(p_vci, mt.getSegmentList(ident), 1), // Constructor for the FSM, with 1 request served at a time
+      ... // other constructors
+{
+    // Constructor code
+    // Set callbacks
+    m_vci_fsm.on_read_write(on_read, on_write);
+
+    // Like any other Caba module:
+    SC_METHOD(transition);
+    dont_initialize();
+    sensitive << p_clk.pos();
+
+    SC_METHOD(genMoore);
+    dont_initialize();
+    sensitive << p_clk.neg();
+}
+}}}
+
+Now for transition and Moore generation, we must also call the fsm:
+
+{{{
+template <typename vci_param>
+void MyComponent<vci_param>::transition()
+{
+    if ( ! p_resetn.read() ) {
+        m_vci_fsm.reset();
+        // Other code specific to MyComponent
+        return;
+    }
+
+    m_vci_fsm.transition();
+
+    // Other code specific to MyComponent
+}
+
+template <typename vci_param>
+void MyComponent<vci_param>::genMoore()
+{
+    m_vci_fsm.genMoore();
+
+    // Other code specific to MyComponent
+}
+}}}
+
+== Callbacks ==
+
+=== On read function ===
+
+This function is called when a read request comes from VCI port.
+
+If the request is a multi-word request, callback will be called once per word.
+
+{{{bool on_read( size_t seg, vci_addr_t addr, vci_data_t &data )}}}
+
+ return value::
+   true if this request is valid, false if not. If false, an error value is returned in response packet for this word.
+ seg::
+   index of the served segment in the list passed in constructor. As segments caracteristics are copied, you may retrieve them with other functions, see below
+ addr::
+   offset in segment, this value is the vci-requested address minus the hit segment base address.
+ data::
+   data value to return in response packet
+
+=== On write function ===
+
+This function is called when a write request comes from VCI port.
+
+If the request is a multi-word request, callback will be called once per word.
+
+{{{bool on_write(size_t seg, vci_addr_t addr, vci_data_t data, int be)}}}
+
+ return value::
+   true if this request is valid, false if not. If false, an error value is returned in response packet for this word.
+ seg::
+   index of the served segment in the list passed in constructor. As segments caracteristics are copied, you may retrieve them with other functions, see below
+ addr::
+   offset in segment, this value is the vci-requested address minus the hit segment base address.
+ data::
+   data value received in the command packet
+ be::
+   byte-enable field from the request
+
+== Other functions ==
+
+ `getSize( size_t segment_index )`::
+   get the size of the handled segment
+ `getBase( size_t segment_index )`::
+   get the base address of the handled segment
+ `getEnd( size_t segment_index )`::
+   get the end address of the handled segment (addresses above are not valid for this segment)
+ `getName( size_t segment_index )`::
+   get the name of the handled segment, for debugging purposes
+ `nbSegments()`::
+   get the cardinal of handled segments set
+ `currentSourceId()`::
+   get the srcid of the currently served request
+