Many users have asked if there are any resources for understanding a protocol. Unfortunately we do not have the resources to fully document the included protocols.
For the simpler protocols, such as those for an SMP, do have a look at the generated HTML protocol tables that are automatically created when Ruby is compiled. However for more complex protocols, like those for a CMP, these tables become much harder to use. For these protocols, I highly recommend using the tester to examine the protocol in action.
Using a small trace is a good starting point. In your $GEMS_ROOT/ruby directory, create a file called "little.trace" which contains the following lines:
7 0x400 0 LD 1 0x400 0 LD 8 0x400 0 LD 12 0x400 0 ST 1 0x400 0 LD
This contains memory references that will be performed serially. The format is processor_id, address, program_counter, operation. For the tester, the PC is irrelevant.
Next, run the tester and feed it the trace file:
./x86-linux/generated/MOESI_CMP_directory/bin/tester.exec -p 16 -a 16 -z little.trace -s 1
This runs the tester with 16 processors, 16 processors/chip, and starts the protocol debug trace at time 1.
After the initialization output, but before the statistics dump, you will see the protocol trace like shown below:
Testing clear stats...Done.
Reading trace from file 'little.trace'...
1 7 -1 Seq Begin > [0x400, line 0x400]
4 1 3 L1Cache Load I>IS [0x400, line 0x400]
139 1 0 L2Cache L1_GETS NP>IGS [0x400, line 0x400]
170 0 0 Directory GETS I>IS [0x400, line 0x400]
321 1 0 L2Cache Data_Exclusive IGS>IGS [0x400, line 0x400]
675 7 -1 Seq Done > [0x400, line 0x400] 674 cycles NULL Yes
675 1 3 L1Cache Exclusive_Data IS>M_W [0x400, line 0x400]
701 1 -1 Seq Begin > [0x400, line 0x400]The first column is the cycle. The second column is more confusing. For those lines that contain "-1 Seq", this column is the actual processor ID. Otherwise the 2nd column is the CHIP ID. The 3rd column is either -1 (for the Seq) or the processor ID on the chip specified by the 2nd column. The 4th column specifies either the controller or "Seq" for the Ruby sequencer (processor interface). The 5th column specifies the actual Event. The 6th column specifies the state transition that occurs and finally the address is shown.
In the output shown above, the Ruby Sequencer begins a request for Processor 7 at time 1. The L1Cache controller for Processor 7, shown as "1 3" for Chip #1, and Proc3 on the chip, triggers the Load event. The next lines shown the events and transitions to complete this Load.