Hi,

I try to understand the behavior of the OR1200 CPU. The hardest thing is that there is no (very very few) comment in the source code, all signal names full of abbreviations, and I have not found documents about the structure/functionalities of the modules/files.

Is there any low-level documentation? (I have found the specification, but no document about the implementation.)
Why there is no comment in OR1200 rtl code?

Br,
Benedek

Agreed, documentation within the RTL and on the implementation is pretty thin on the ground.

I vaguely recall an implementation manual from years ago, but I'm not sure where it'd be online.

You could look at the mor1kx - https://github.com/openrisc/mor1kx

That's a re-write of basically the same thing as the OR1200 (in order, a handful of pipeline stages, MMUs, caches) and is more advanced in that it supports multicore. Again, implementation docs were never really completed, but the RTL is much better in terms of documentation.

Agreed. I and a few of my students are struggling to understand the source code for the last few months. Mostly, it follows the pipelined processor described in Henessy and Patterson's textbook. Unfortunately, there are a few mysterious signals whose purpose are totally opaque to us. In some cases it takes weeks to understand them, weeks which could be spared if the author bothered to comment his code properly..

I think that openrisc's popularity will get a boost if it is properly commented.

As we read and understand openrisc, we comment the source code and draw diagrams which show the inner workings of the modules. If we understand it sufficiently, we will put our commented version to the internet, together with the diagrams.

Could it be that the RTL is generated from another codebase? This seems to be pretty common with modern "open source" RTL projects.

Dear proclus -



There is a lot of legacy in the OpenRISC project, which unfortunately cannot be undone.
What a community based project could do though, is to slowly move forward with renewed energy and the good will to make things better, and possibly in a better way.



Perhaps the OpenRISC architecture in recent years is no more the most advanced out there,
but it definitely still is a great learning tool. That is why the OpenCores community still believes in its purpose; and in a way still finds OpenCores its natural birth place.



Any plans on where to host your useful contribution to the project?
The status of the OpenRISC and its development seems a bit scattered at the moment.

As the maintainers and developers of the OpenCores community portal, we hope this project will get picked-up and improved again; and we are willing to help out with giving it back the home it once had.

Best,
/:/ OC-team

I fully agree that documentation and easy accessible diagrams are vital. I know of many places where it is used in education, but unfortunately very little of that has been made publicly available.

When it comes to OpenRISC implementations, or1200 hasn't been touched in years and at this point it's missing several features that is more or less required to properly run Linux nowadays (such as atomic operations) mor1kx though is still in semi-active development and we are happy to receive patches for documentation and code at https://github.com/openrisc/mor1kx

Since a couple of years, the entry point for OpenRISC in general is https://openrisc.io/ and at https://github.com/openrisc/ you will find the latest toolchain, Linux kernel, C libraries etc. We have also tried to collect all tutorials related to OpenRISC at https://openrisc.io/tutorials

Olof Kindgren,
Core OpenRISC developer

I'll second that suggestion that the mor1kx be used, particularly the cappuccino pipeline implementation, for any educational or documentation efforts. It's by far the most complete OpenRISC implementation out there. The code is mostly pretty well commented. I started a documentation an effort when the core was being designed but sadly it's far from complete.

ETH Zurich also have some OpenRISC cores but I'm not sure if they've been released, but they could be well documented. You could try contacting someone there to ask if they'd put them up on github with any docs. Search for "openrisc" on this page: http://iis-projects.ee.ethz.ch/index.php/PULP

There was an implementation manual for the OR1200 I saw years ago; have you managed to get a copy of that? It'll be way out of date these days, but it may help with the particular query you have.

Anyway, also with Olof's suggestion, the OpenRISC community set up the openrisc.io site a few years ago, OpenCores looks like it's come back to life and it's nice this forum is still getting used, but you might try asking on OpenRISC mailing list on LibreCores.org to reach a wider audience: https://lists.librecores.org/listinfo/openrisc

Sorry for my late response.. I must confess that I wasnt expecting any replies to my post..

"......Any plans on where to host your useful contribution to the project?....."

Well, it can be in our department's website (marmara university computer engineering department), or in any other place which desires to host it. But before that, we have to come to a complete understanding of the source first.. Deciding on where to host the documentation is the least of our worries now.. :-)

Actually, it would be very nice for us if we can direct some questions about the source code to the developers, if that is possible. Most of the source is very clear and understandable, the only part we have difficulty in understanding currently relates to the interaction of openrisc with dcache and icache. For example, take the signal lsu_unstall. It seems to thaw an if freeze for just one cycle after an acknowledge from dcache is received. But what is the purpose for this? And how does it interact with wait_lsu signal? Most importantly, what are the race conditions that gave rise to these signals?

Also, some signals seem to do no useful work. One example is force_dslot_fetch..

As for mor1kx: we have already spent a considerable amount of time on openrisc and want to finish reading it first before switching to mor1kx..