[libre-riscv-dev] Documenting the SOC tree Repository

[libre-riscv-dev] Documenting the SOC tree Repository

[Yehowshua]

I’m reading the rather large SOC repository right now.
I’m creating documentation as I go along.
This may take a few weeks.

Yehowshua
_______________________________________________
libre-riscv-dev mailing list
libre-riscv-dev@lists.libre-riscv.org
http://lists.libre-riscv.org/mailman/listinfo/libre-riscv-dev

Re: [libre-riscv-dev] Documenting the SOC tree Repository

[Luke Kenneth Casson Leighton]

On Saturday, May 2, 2020, Yehowshua <yimmanuel3@gatech.edu> wrote:

> I’m reading the rather large SOC repository right now.


it's not that biig.  err is it?

the IEEE754FPU one i know is around 10,000 lines.  as python projects go
that's pretty small.

I’m creating documentation as I go along.


fantastic.  i do recommend leaving out minerva except perhaps some
commentary about it at the top level, that we intend to borrow its use of
wishbone and its L1 I and D cache code, to save on both development and
unit test time.

in particular it has a formal correctness proof for the L1 cache.

sadly we didn't yet put in an NLNet grant request to cover documentation,
which we still could do if you like?


one suggestion / request, if you create a page to describe some classes
(whatever) please do cross-reference them *in the actual code*.

make sure to commit and push pretty much immediately.  under no
circumstances go "i'll commit these and wait a few days before pushing
them".


> This may take a few weeks.


not a surprise.

l.



-- 
---
crowd-funded eco-conscious hardware: https://www.crowdsupply.com/eoma68
_______________________________________________
libre-riscv-dev mailing list
libre-riscv-dev@lists.libre-riscv.org
http://lists.libre-riscv.org/mailman/listinfo/libre-riscv-dev

Re: [libre-riscv-dev] Documenting the SOC tree Repository

[Yehowshua]

> On May 2, 2020, at 12:40 AM, Luke Kenneth Casson Leighton <lkcl@lkcl.net> wrote:
> 
> sadly we didn't yet put in an NLNet grant request to cover documentation,
> which we still could do if you like?

Don’t worry about NLNet for me. Should things go according to plan, I should be doing this full time come August anyways.

Yehowshua
_______________________________________________
libre-riscv-dev mailing list
libre-riscv-dev@lists.libre-riscv.org
http://lists.libre-riscv.org/mailman/listinfo/libre-riscv-dev

Re: [libre-riscv-dev] Documenting the SOC tree Repository

[Yehowshua]

Also - I’d like to clean up the decoder a bit. I’ll go ahead and make a branch and push to that…

I’ll have you guys review periodically.

Yehowshua
_______________________________________________
libre-riscv-dev mailing list
libre-riscv-dev@lists.libre-riscv.org
http://lists.libre-riscv.org/mailman/listinfo/libre-riscv-dev

Re: [libre-riscv-dev] Documenting the SOC tree Repository

[Luke Kenneth Casson Leighton]

On Saturday, May 2, 2020, Yehowshua <yimmanuel3@gatech.edu> wrote:

> Also - I’d like to clean up the decoder a bit. I’ll go ahead and make a
> branch and push to that


i really do not like branches.  please, really: do not use them except
under absolute dire critically necessary circumstances.  i documented thus
in HDL_workflow.


> I’ll have you guys review periodically.


please, follow the HDL_workflow.  it is there for a reason.

use the unit tests, make sure anything you do works 100%.  work
incrementally (5 to 15 lines per commit is perfectly acceptable) and commit
directly to the master branch.  do not be afraid to make 20 to 40 commits
*a day*.  untested code that is comoletely unused is perfectly fine.

yes it means that you really do have to be certain that what you commit is
going to work, and that's the whole point.

by working in master, you *have* to be strict, keep to small changes, and
keep constantly in touch.

not "periodically commit because i'm hiding what i am working on because i
don't want anyone to see it in case they criticise it because it's neither
perfect nor complete"

that is *not* collaboration!

so if you find that you are not 100% confident, because a unit test is
missing, write and commit the unit test, *then* make the incremental
change, make sure the unit tests pass, and then git push.

this is described on http://libre-soc.org/HDL_workflow

if you absolutely must make large changes, they can be done by writing the
leaf nodes of alternatives, then when it comes to changing the code that
uses the alternatives, writing classes with alternative implementations
that are *dynamically chosen* at runtime, through a config file and so on.

there's other techniques as well.

l.



-- 
---
crowd-funded eco-conscious hardware: https://www.crowdsupply.com/eoma68
_______________________________________________
libre-riscv-dev mailing list
libre-riscv-dev@lists.libre-riscv.org
http://lists.libre-riscv.org/mailman/listinfo/libre-riscv-dev

Re: [libre-riscv-dev] Documenting the SOC tree Repository

[Yehowshua]

> On May 2, 2020, at 7:24 PM, Luke Kenneth Casson Leighton <lkcl@lkcl.net> wrote:
> 
> i really do not like branches. 

OK no branches. I’d like to move the CSVs to the soc repo, and then do an iframe to the git tree raw to display in the wiki.

I can wrap it in a little js to get the browser to render the csv as a table.

It doesn’t make sense to submodule the entire wiki in the SOC repo just for some tables. That’s structurally wrong.

Moving the CSVs directly into the SOC repo is low priority for me now - but, I’m just putting it out there - its something that needs to be addressed sooner than later.

Yehowshua
_______________________________________________
libre-riscv-dev mailing list
libre-riscv-dev@lists.libre-riscv.org
http://lists.libre-riscv.org/mailman/listinfo/libre-riscv-dev

Re: [libre-riscv-dev] Documenting the SOC tree Repository

[Yehowshua]

Apologies - this should have been in the big-tracker.

Yehowshua

_______________________________________________
libre-riscv-dev mailing list
libre-riscv-dev@lists.libre-riscv.org
http://lists.libre-riscv.org/mailman/listinfo/libre-riscv-dev

Re: [libre-riscv-dev] Documenting the SOC tree Repository

[Luke Kenneth Casson Leighton]

On Sunday, May 3, 2020, Yehowshua <yimmanuel3@gatech.edu> wrote:

>
>
> > On May 2, 2020, at 7:24 PM, Luke Kenneth Casson Leighton <lkcl@lkcl.net>
> wrote:
> >
> > i really do not like branches.
>
> OK no branches


appreciated.


>  I’d like to move the CSVs to the soc repo, and then do an iframe to the
> git tree raw to display in the wiki.


a simpler proposal is to write a script that commits and copies the files
to the other (ikiwiki) repo.

some instructions can be placed in isatables indicating where the canonical
versions are (in soc).

however this again leaves


> I can wrap it in a little js to get the browser to render the csv as a
> table.


hm hm that makes js a hard dependency where it presently is not.

i wonder if the postcommit hook in ikiwiki could be modified to pretend
that the files are in the same repo.  the static html would then be built
still from the same source.


>
> It doesn’t make sense to submodule the entire wiki in the SOC repo just
> for some tables. That’s structurally wrong.


i honestly don't know the best option here.  duplication risks getting out
of sync.  all ootions have disadvantages


> Moving the CSVs directly into the SOC repo is low priority for me now -
> but, I’m just putting it out there - its something that needs to be
> addressed sooner than later.


the postcommit option i can ask alain if he can have a look.

l.



>
> Yehowshua
> _______________________________________________
> libre-riscv-dev mailing list
> libre-riscv-dev@lists.libre-riscv.org
> http://lists.libre-riscv.org/mailman/listinfo/libre-riscv-dev
>


-- 
---
crowd-funded eco-conscious hardware: https://www.crowdsupply.com/eoma68
_______________________________________________
libre-riscv-dev mailing list
libre-riscv-dev@lists.libre-riscv.org
http://lists.libre-riscv.org/mailman/listinfo/libre-riscv-dev