PortsAndApis

Ports and APIs

Overview

APIoverview.png

Note: The left derivation tree is the deprecated dynamic casts version.

For this example implementation the following choices were made (see below for the options):

  • One API for a PCIe device (not divided into Master and Slave part) with one port (not Master and Slave port).
  • Provide functions for manipulating TLPs in the access classes (PCIe[Master|Router|Slave]Access). Creation of tranactions in PCIeAPI.
  • Receiving and processing of TLPs in the slave: Pass the received transaction directly to the user (3). Convenience methods in the access class may be used for processing. Callbacks may be realized later in the PCIeAPI.

Options

Question: Two APIs (One Master- and one Slave-API) or one combined API?

The combined API owns a PCIeMasterPort and a PCIeSlavePort and hence is able to receive and send PCIe packets. In the PCIe specification the devices are not divided into masters and slaves.

PortsAndAPIs.jpg
Disadvantage: PCIe devices are not categorized as master or slave.		 or ImageLink(PortsAndAPI.jpg
Advantage: Better representation of PCIe philosophy, which has no masters and slaves.

We chose this option. A modification of the basic initiator_ports leads to only one bidirectional port which is needed by the API:
PortAndAPI.png
With this one port it is again possible to inherit from the port so binding of the API may be done as it is a port.

The PCIeMasterPort provides blocking communication used by the PCIeMasterAPI.

The PCIeSlavePort provides blocking communication used by the PCIeSlaveAPI.

PCIeMasterAPI (or master part of PCIeAPI)

Derived from PCIeMasterPort.

  • Uses blocking communication

Possibilities: 

 (!) Provide API methods in PCIe(Master)API (classical doing)
      • Provides high-level-calls to the user, e.g. send_Memory_Write(addr, data,...)
      • Creates transactions with (inline) initialization methods which create the matching transaction.
      • Send transaction with blocking Transact method. (May be replaced with non-blocking notify later.)
      • : Example:

  1. class PCIeMasterAPI {
  2.   send_Mem_Write(many, many, many, ...) {
  3.     container = init_Mem_Transaction(many, many, many, ...);
  4.     b_transact(container);
  5.   }
  6.  
  7.   inline container init_Mem_Write_Transaction(many, many, many, ...) {
  8.     ... // create Transaction Container
  9.   }
  10. };

 (!) Provide API methods in PCIeMasterAccess (not in PCIe(Master)API)
      • Get (generate) transaction object out of (in) PCIe(Master)API
      • Prepare transaction according to the needed TLP type by calling API methods in PCIeMasterAccess
      • Send transaction with PCIe(Master)API
      • Advantage:
          • Decouples TLP data processing API (PCIeMasterAccess) from notification API (PCIe(Master)API).
          • Extensibility: Extension of the Transaction Container does not result in a change if the PCIe(Master)API but only a change of PCIeMasterAccess (which has to be adapted anyway). So a slave module need not care about extended transactions (if it does not need the extension) because the API keeps the same. A slave who is interested in the extension simply casts the transacted transaction (received with b_transact) to the extended type.

   Example:
  1. class MyModule {
  2.   ...
  3.   void action() {
  4.     // Get transaction object
  5.     PCIeMasterAccessHandle ah = myPCIeAPI.create_transaction();
  6.     // Prepare transaction
  7.     std::vector<gs_uint8> data; ...
  8.     ah->init_Memory_Write( 0x1B39A34, *dat, data_size );
  9.     // Send transaction
  10.     myPCIeAPI.send(ah)
  11.     // process reaction
  12.     if (ah->get_Completion_Status() == SuccessfulCompletion)
  13.       ...
  14.   }
  15. };

PCIeSlaveAPI (or slave part of PCIeAPI)

Derived from PCIeSlavePort.

  • The method b_transact is target of the blocking master call

 Possibilities:
  (!) '''1)''' Give the slave the opportunity to register callback function(s):<br>
      API methods located in PCIe(Slave)API (classical doing)<br>
      See section below for different solutions.<br>
      ''Disadvantage'': One additional method call inside the callback adapter.
            • Register different functions (with different signatures) for different TLP types. These callback functions will be called on reception of such a transaction. TLP types without a registered callback either will be processed in the b_transact method or will result in a warning.
            • Register different functions (with the same signature) for different TLP types.

  (!) '''2)''' The slave has to implement an interface so that the API is able to call fixed defined callback functions (e.g. for each TLP type).<br>
      API methods located in PCIe(Slave)API (classical doing)<br>
      ''Advantage'': Faster than variable callback registration (one less method call).<br>
      ''Disadvantage'': Less flexible user implementation.

  (!) '''3)''' Pass the call directly to the user slave (b_transact)<br>
      API methods located in PCIeSlaveAccess (not in PCIe(Slave)API)<br>
      The user module has to implement tlm_b_if and bind itself to the API (as the API binds itself to the port).<br>
      Access methods to different TLP types are in the Transaction Container (or Access methods).<br>
      ''Advantage'': Matches the concept which provides processing methods in the transaction's PCIeSlaveAccess methods.<br>
      ''Disadvantage'': One additional method call to call the user's b_transact.
(!) 1) (!) Different Callback Function Alternatives

For registering callback functions in the API we have different alternatives:

  1. Use consistent method signatures for registration.
  2. :2. Use different method signatures for registering different TLP types.

Consistent method signatures for registration

  • Use a unified adapter class which can be used within a registration macro (see GreenConfig).

  1. template<class T>
  2. class CallbAdapt
  3. : public CallbAdapt_b
  4. {
  5.   typedef void (T::*callb_func_ptr)(const PCIeSlaveAccessHandle);
  6.  
  7. public:
  8.  
  9.   CallbAdapt(T *ob, callb_func_ptr _ptr);
  10.  
  11.   /// Makes the callback, called by the base class CallbAdapt_b.
  12.   void call(const PCIeSlaveAccessHandle);
  13.  
  14. };

  • Select the TLP type with an enumeration, e.g.:

  1. enum TLPtype {
  2.   MemoryWrite = 0,
  3.   MemoryRead,
  4.   IOWrite,
  5.   IORead,
  6.   ...
  7. };

  • Use a unified macro with a corresponding unified method for registration and specify the call with the TLPtype:

  1. // Macro for registering callback functions (see method registerCallback).
  2. #define REGISTER_CALLBACK(class, method, TLPtype)                \
  3.   register_Callback(TLPtype, new tlm::gc::config::CallbAdapt<class>(this, &class::method));

  • Hold the function pointers in a vector with index TLPtype.

Advantage:

  • Simpler code: unified code for all different types of TLPs
  • User has all opportunities in processing the transaction (he gets the original AccessHandle).

Disadvantage:

  • User has - when processing the transaction - to choose the relevant quarks out of the not filtered transaction container (AccessHandle).

Different method signatures for registering different TLP types

  • Use a separate adapter classes one for each TLP type.

  1. template<class T>
  2. class MemWriteCallbAdapt
  3. : public MemWriteCallbAdapt_b
  4. {
  5.   typedef void (T::*callb_func_ptr)(const type1, const type2, ...);
  6.  
  7. public:
  8.  
  9.   CallbAdapt(T *ob, callb_func_ptr _ptr);
  10.  
  11.   /// Makes the callback, called by the base class CallbAdapt_b.
  12.   void call(const type1, const type2, ...);
  13.  
  14. };

  • Use separate macros and separate methods for processing the callback registration.

  1. // Macro for registering callback functions (see method registerCallback).
  2. #define REGISTER_MEM_WRITE_CALLBACK(class, method)                \
  3.   register_Memory_Write_Callback(new tlm::gc::config::MemWriteCallbAdapt<class>(this, &class::method));

  • Use the TLP type enumeration (see above) for holding function pointers in a vector.

Advantage:

  • Bigger, more confusing code: separate code (adapter, macro and register function) for all different types of TLPs
  • User gets only the quarks, which are relevant for this TLP type.

Disadvantage:

  • User is limited to the passed quarks when processing the transaction. Possible solution: in addition the original AccessHandle may be passed.

(!) 2) (!) Fixed interface, which user has to implement
  • PCIeAPI gets pointer to user module during instantiation and can call directly the processing method(s)
      • Either: One method which processes all kinds of TLP types

  1. class PCIe_callback_if {
  2.   virtual void receive_TLP(PCIeAccessHandle) = 0;
  3. };
      • Or: different methods for each TLP type, e.g.

  1. class PCIe_callback_if {
  2.   virtual void receive_Memory_Write(address, length, data, sender) = 0;
  3.   virtual void receive_Memory_Read(address, length, data, sender) = 0;
  4.   virtual void receive_Message(messageCode, data, sender) = 0;
  5. };

  • OR: The user module may implement several interfaces, each one for one callback method for one TLP type. Only implemented interface methods will be called by the API, others are ignored (warning). E.g.:

  1. class PCIe_Memory_Write_callback_if {
  2.   virtual void receive_Memory_Write(address, length, data, sender) = 0;
  3. };
  4.  
  5. class PCIe_Memory_Read_callback_if {
  6.   virtual void receive_Memory_Read(address, length, data, sender) = 0;
  7. };
  8.  
  9. class PCIe_Message_callback_if {
  10.   virtual void receive_Message(messageCode, data, sender) = 0;
  11. };

(!) 3) (!) Directly pass into user module

The receiving PCIeAPI calls the b_transact method which is implemented by the user module.

The user has to implement the interface PCIe_recv_if and 'bind' it to the API by giving it to the constructor of the PCIeAPI instance:

  1. using namespace tlm;
  2. using namespace tlm::PCIe;
  3.  
  4. class MyModule
  5.  : public sc_module,
  6.    public PCIe_recv_if
  7. {
  8. public:
  9.   PCIeAPI myAPI;
  10.  
  11.   MyModule(sc_module_name name)
  12.    : sc_module(name),
  13.      myAPI("PCIeAPI", this)
  14.   {
  15.   }
  16.  
  17.   virtual void b_transact(PCIeTransactionHandle th) {
  18.     PCIeSlaveAccessHandle ah = _getSlaveAccessHandle(th);
  19.  
  20.     switch((unsigned int)th->get_TLP_type()) {
  21.       case MemWrite:
  22.       ...
  23.     }
  24.   }
  25. }

The Transaction Container access methods provide convenience methods to access data according to the TLP type. E.g.:

  1.  class PCIeMasterAccess
  2.    : public virtual GenericMasterAccess
  3.   {
  4.   public :
  5.     void init_Memory_Write( MAddr targetAddr, std::vector<gs_uint8> data, unsigned int data_size );
  6.     ...
  7.   };

  1.  class PCIeSlaveAccess
  2.    : public virtual GenericTargetAccess
  3.   {
  4.   public :
  5.     const MPCIeCmd& get_TLP_type() const;
  6.  
  7.     const MAddr& get_addr() const;
  8.  
  9.   };

Callbacks may be added later in the API. Then the API would have to process the incoming transaction instead of just forwarding it to the user module's b_transact method.

Configuration Registers
see Configuration Registers
‹ PcieRoutingupRegressionTests ›

Posted January 8th, 2008 by MarkBurton