[J-core] json instructions set

[Cedric BAIL]

Hi Jeff,

On Mon, Jun 26, 2017 at 10:28 PM, D. Jeff Dionne
<Jeff at se-instruments.co.jp> wrote:
> On Jun 27, 2017, at 9:12, Cedric BAIL <cedric.bail at free.fr> wrote:
>> So I have been working on making
>> http://www.shared-ptr.com/sh_insns.html more usable for developping
>> new instructions as I think we are taking the road of adding more of
>> them in the future and we need also an easier way to discuss future
>> propoal I think.
>
> Thanks for that, (the) one thing missing from the J-Core IP set is a coherent documentation suite.
>
>> I have put my work on https://github.com/Bluebugs/sh-insns . It
>> require to be installed either locally or on a webserver. It doesn't
>> require any database or anything, it uses client side Javascript for
>> everything (which make it a bit heavy on your computer, but it isn't
>> too bad considering the benefit). This new webpage allow for sorting,
>> filtering and regexp based search on the entire instructions set (and
>> you can combine this together). The instructions themself are actually
>> described in a separate JSON file (thus the title of the email) that
>> would allow pull request discussion for expanding the J-Core
>> instructions set.
>
> The CPU core decoder RTL is automatically generated from an OpenDoc spreadsheet at the moment.  This may or may not have been a good choice, but it was at least fairly easy to work with.  Javascript might have been better.

I have started looking at it, but was a bit too much of work for me
for the time I had, that why I switched to do something that I deemed
a better use of my time. I may have to go back at it later.

> The javascript and the .ods diverge in purpose, with the .ods specifying pipeline control, and this new javascript trying to document.  And and still there remains 2 (or 1 1/2) problems unsolved by either, the autogeneration of a (hopefully, cycle accurate) simulator and databook quality instruction set reference.  I had this vague idea that the documentation web pages would display a pipeline diagram, and show cycle by cycle what happens...

> I have been thinking that what we need is a source format that generates all of these things.  The javascript seems a better place to start from a structure point of view, likely importing the information in the .ods from the RTL distribution.

I would love to see this. I guess that a possible evolution would be
to have the information of the ods injected inside the JSON and
generate things from it. I definitively like the idea of having a web
page display the pipeline diagram with a cycle by cycle animation of
what the instruction does. It is also pushing for going into the
direction of using more Javascript related technologie.

>> As I know there will be discussion regarding the license, it is
>> currently under GPLv3, but it can be relicensed to whatever any one
>> really prefer.
>
> BSD, please.  Especially if it is going to become the source material for the instruction set.

Done, moved to 2-Clause BSD License.

>> I don't think this work is impacted by the original
>> license of the code that generate
>> http://www.shared-ptr.com/sh_insns.html (GPLv3 doesn't apply on the
>> output of the program and you can run that program locally). I have
>> also not extracted the svg that the original site contain to not be
>> affected by the GPLv3. So all in all, I think this is fine to be
>> relicensed (I have checked in the node.js script I have used to
>> extract the information and I made sure that all manual modification
>> where visible in the git history).
>>
>> My hope here would be that the J-Core project accept this as the first
>> J-Core github project and that we can use this for future discussion
>> on new instructions. Maybe it could also become a documentation
>> repository for the J-Core in general (This file only cover
>> instructions for the  moment and there is clearly more to a CPU than
>> just its instructions set).
>
> More than happy to see if we can do that, yes!
>
> One thing I want to caution:  Instruction set extensions are guarded like the crown jewels.  It really, really is internally here a consensus process, with a case needing to be made for -why- they precious encoding space should be used.  There have been a large number of proposed formats, space reservations, coprocessor encodings, etc proposed... nothing has ever reached consensus with the exception of CAS.L.  Of course, the best way to get such a proposal adopted is to show it's value, so we encourage experimentation.  BGB's independent experiments for instance with compilers other than GCC and LLVM, instructions etc, while not a part of the project contribute experimental results.  It is unlikely, for instance, that a 64bit mode that isn't carefully designed, including instruction frequency counts from mainstream compiler ports, could go into either J-Core documentation or RTL repos.

I fully agree with you here as this would be like any open source
project. Discussing goal, building a proposal and getting a consensus
before it become accepted and merged.

I have some personnal idea that I will later write another email about
to describe my goal and general idea to get feedback to check the
general direction I am heading to, but I wouldn't ask a pull request
before I have enough assembly example and some numbers from gcc or
llvm. Ideally I would like to be able to actually have some patch for
J-Core vhdl.

> I mention this caution because if it does become the documentation set for the cores, it has to reflect the stable, mature status of the ISA and Cores.  Experimental stuff can always go into separate repos...

Yes, if it is on J-Core github, I would expect it to reflect only what
is stable, mature and can be relied on.

Cedric