wiki:Component/Iss2Api

Instruction Set Simulator generic API

This new API is an evolution of the ISS API. New features are:

  • Use structs rather than arguments, this eases API evolution (which can be acomplished through carefully choosed default values);
  • support for CPU modes;
  • support for generic Memory management unit.

Structures and values

Enumerated values

Execution mode for any Instruction/Data access, checked by mode-enabled caches

    enum ExecMode {
        MODE_HYPER,
        MODE_KERNEL,
        MODE_USER,
    };

Operation type on Data cache access

    enum DataOperationType {
        DATA_READ,
        DATA_WRITE,
        DATA_LL,
        DATA_SC,
        XTN_WRITE,
        XTN_READ,
    };

When operation is XTN_READ or XTN_WRITE, address field must be one of these values, that determines the extended access type.

register name index description mode
MMU_PTPR 0 Page Table Pointer Register R/W
MMU_MODE 1 Data & Inst TLBs and caches Mode Register R/W
MMU_ICACHE_FLUSH 2 Instruction Cache flush W
MMU_DCACHE_FLUSH 3 Data Cache flush W
MMU_ITLB_INVAL 4 Instruction TLB line invalidation W
MMU_DTLB_INVAL 5 Data TLB line Invalidation W
MMU_ICACHE_INVAL 6 Inst Cache line invalidation (vaddr) W
MMU_DCACHE_INVAL 7 Data Cache line invalidation (vaddr) W
MMU_ICACHE_PREFETCH 8 Instruction Cache line prefetch W
MMU_DCACHE_PREFETCH 9 Data Cache line prefetch W
MMU_SYNC 10 Complete pending writes W
MMU_IETR 11 Instruction Exception Type Register R
MMU_DETR 12 Data Exception Type Register R
MMU_IBVAR 13 Instruction Bad Virtual Address Register R
MMU_DBVAR 14 Data Bad Virtual Address Register R
MMU_PARAMS 15 Caches & TLBs hardware parameters R
MMU_RELEASE 16 Generic MMU release number R
MMU_WORD_LO 17 LSB for double word access R/W
MMU_WORD_HI 18 MSB for double word access R/W
MMU_ICACHE_PA_INVAL 19 Inst Cache line invalidation (paddr) W
MMU_DCACHE_PA_INVAL 20 Data Cache line invalidation (paddr) W
MMU_LL_RESET 21 LLSC reservation buffer invalidation W

Instruction request

Instruction request, only significant if `valid' is asserted. addr must be 4-byte aligned.

    struct InstructionRequest {
        bool valid;
        addr_t addr;
        enum ExecMode mode;
    };

Instruction response

Valid is asserted when query has beed satisfied, if no request is pending, valid is not asserted.

instruction is only valid if no error is signaled.

    struct InstructionResponse {
        bool valid;
        bool error;
        data_t instruction;
    };

Data request

Data request, only significant if `valid' is asserted. addr must be 4-byte aligned. wdata is only significant for be-masked bytes.

  • wdata[7:0] is at ![addr], masked by be[0]
  • wdata[15:8] is at [addr+1], masked by be[1]
  • wdata[23:16] is at [addr+2], masked by be[2]
  • wdata[31:24] is at [addr+3], masked by be[3]

When type is XTN_READ or XTN_WRITE, addr must be an opcod of enum ExternalAccessType. For extended access types needing an address, address is passed through the wdata field.

    struct DataRequest {
        bool valid;
        addr_t addr;
        data_t wdata;
        enum DataOperationType type;
        be_t be;
        enum ExecMode mode;
    };

Data response

Valid is asserted when query has beed satisfied, if no request is pending, valid is not asserted.

data is only valid if no error is signaled.

Read data is aligned with the same semantics than the wdata field in struct DataRequest. Only bytes asserted in the BE field upon request are meaningful, others have an undefined value, they may be non-zero.

    struct DataResponse {
        bool valid;
        bool error;
        data_t rdata;
    };

Functions

void reset()

Reset processor internal register. Iss must behave like the processor receiving a reset cycle.

void getRequests( struct InstructionRequest &, struct DataRequest & )

Iss must populate the request fields.

uint32_t executeNCycles( uint32_t ncycle, const struct InstructionResponse &, const struct DataResponse &, uint32_t irq_bit_field )

Tell the Iss to execute *at most* ncycle cycles, knowing the values of the responses and the value of all the irq lines. The responses may not be valid. Each irq is a bit in the irq_bit_field word.

Iss must return the number of cycles it actually executed, knowing the inputs (responses and irqs) won't change. This number is at most ncycle. The ncycle argument may be 0 if wrapper only wants the ISS to handle its inputs, but not actually change the processor state. This is mostly used on GDB breakpoints.

bool virtualToPhys(addr_t &addr) const

Iss translate virtual address to physical address if it the processor contains an internal MMU. It returns false if the virtual address is not mapped. This function does nothing but returning true if no MMU is implemented in the Iss.

void setWriteBerr()

The cache received an imprecise write error condition, this signalling is asynchronous.

Other APIs

Sideband signals

In order to inform the ISS about some cache caracteristics, those functions have been defined.

Their implementation is optional.

void setCacheInfo( const struct CacheInfo &info )

Informs the Iss avout the cache caracteristics. New fields could be added in the Iss2::CacheInfo definition. Current definition is:

struct CacheInfo
{
    bool has_mmu;
    size_t icache_line_size;
    size_t icache_assoc;
    size_t icache_n_lines;
    size_t dcache_line_size;
    size_t dcache_assoc;
    size_t dcache_n_lines;
};

This function supersedes the two folling deprecated ones.

For backwards compatibility, default implementation of setCacheInfo() calls setICacheInfo and setDCacheInfo.

void setICacheInfo( size_t line_size, size_t assoc, size_t n_lines ) [deprecated]

Inform the Iss about the instruction cache caracteristics

void setDCacheInfo( size_t line_size, size_t assoc, size_t n_lines ) [deprecated]

Inform the Iss about the data cache caracteristics

Debugger API

This API is optional, it serves to expose the internal ISS registers to a debugger.

The debugger API is ISS-architecture independant.

unsigned int debugGetRegisterCount()

Iss must return the count of registers known to GDB. This must follow GDB protocol for this architecture.

debug_register_t debugGetRegisterValue(unsigned int reg)

Accessor for an Iss register, register number meaning is defined in GDB protocol for this architecture.

void debugSetRegisterValue(unsigned int reg, debug_register_t value)

Accessor for an Iss register, register number meaning is defined in GDB protocol for this architecture.

size_t debugGetRegisterSize(unsigned int reg)

Get the size for a given register. This is defined in GDB protocol for this architecture.

void dump()

Dumps internal state of the ISS on std::cout. This is used by instrumentation tools which want to display the state of an ISS at a certain event.

void set_debug_mask() and the m_debug_mask variable

set_debug_mask() is a public method for enabling processor-specific debug messages. 0 always mean "all debug messages are disabled", other values a processor-specific. Processor implementations may access the m_debug_mask member to conditionally enable debug messages.

Implementation notes

executeNCycles semantics

When executeNCycles is called, instruction and data requests previously retrieved through getRequests() may not be satisfied yet.

As executeNCycles ensures responses MUST NOT change for at least ncycle:

  • an ISS frozen for a Data miss MAY continue to fetch Instructions
  • an ISS frozen for an Instruction miss MAY continue to do Data accesses
  • an ISS frozen for a Data miss MUST not change Data access until satisfied
  • an ISS frozen for a Instruction miss MAY change Instruction request (if receiving an IRQ and jumping to ISR while stalled, for instance)
  • an ISS running because all its instruction and data accesses are satisfied SHOULD run as long as no other request needs to be answered by cache.
Last modified 10 years ago Last modified on Feb 12, 2013, 12:54:09 PM