Skip to content

Commit 7f5f5b4

Browse files
mithromithro
committed
Adding initial structure from Project X-Ray.
Signed-off-by: Tim 'mithro' Ansell <[email protected]>
0 parents  commit 7f5f5b4

File tree

5 files changed

+372
-0
lines changed

5 files changed

+372
-0
lines changed

‎.update-contributing.py

+36
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
#!/usr/bin/env python3
2+
3+
# Header
4+
contrib = ["""\
5+
# Contributing to Project X-Ray
6+
"""]
7+
8+
# Extract the "Contributing" section from README.md
9+
found = False
10+
for line in open('README.md'):
11+
if found:
12+
if line.startswith('# '):
13+
# Found the next top level header
14+
break
15+
contrib.append(line)
16+
else:
17+
if line.startswith('# Contributing'):
18+
found = True
19+
20+
# Footer
21+
contrib.append(
22+
"""\
23+
24+
25+
26+
27+
28+
29+
----
30+
31+
This file is generated from [README.md](README.md), please edit that file then
32+
run the `./.update-contributing.py`.
33+
34+
""")
35+
36+
open("CONTRIBUTING.md", "w").write("".join(contrib))

‎CODE_OF_CONDUCT.md

+46
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
# Contributor Covenant Code of Conduct
2+
3+
## Our Pledge
4+
5+
In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation.
6+
7+
## Our Standards
8+
9+
Examples of behavior that contributes to creating a positive environment include:
10+
11+
* Using welcoming and inclusive language
12+
* Being respectful of differing viewpoints and experiences
13+
* Gracefully accepting constructive criticism
14+
* Focusing on what is best for the community
15+
* Showing empathy towards other community members
16+
17+
Examples of unacceptable behavior by participants include:
18+
19+
* The use of sexualized language or imagery and unwelcome sexual attention or advances
20+
* Trolling, insulting/derogatory comments, and personal or political attacks
21+
* Public or private harassment
22+
* Publishing others' private information, such as a physical or electronic address, without explicit permission
23+
* Other conduct which could reasonably be considered inappropriate in a professional setting
24+
25+
## Our Responsibilities
26+
27+
Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior.
28+
29+
Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful.
30+
31+
## Scope
32+
33+
This Code of Conduct applies both within project spaces and in public spaces when an individual is representing the project or its community. Examples of representing a project or community include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. Representation of a project may be further defined and clarified by project maintainers.
34+
35+
## Enforcement
36+
37+
Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at [[email protected]](mailto:[email protected]). All complaints will be reviewed and investigated and will result in a response that is deemed necessary and appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately.
38+
39+
Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project's leadership.
40+
41+
## Attribution
42+
43+
This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, available at [http://contributor-covenant.org/version/1/4][version]
44+
45+
[homepage]: http://contributor-covenant.org
46+
[version]: http://contributor-covenant.org/version/1/4/

‎CONTRIBUTING.md

+81
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
# Contributing to Project X-Ray
2+
3+
There are a couple of guidelines when contributing to Project Trellis which are
4+
listed here.
5+
6+
### Sending
7+
8+
All contributions should be sent as
9+
[GitHub Pull requests](https://help.github.com/articles/creating-a-pull-request-from-a-fork/).
10+
11+
### License
12+
13+
All code in the Project X-Ray repository is licensed under the very permissive
14+
[ISC Licence](COPYING). A copy can be found in the [`COPYING`](COPYING) file.
15+
16+
All new contributions must also be released under this license.
17+
18+
### Code of Conduct
19+
20+
By contributing you agree to the [code of conduct](CODE_OF_CONDUCT.md). We
21+
follow the open source best practice of using the [Contributor
22+
Covenant](https://www.contributor-covenant.org/) for our Code of Conduct.
23+
24+
### Sign your work
25+
26+
To improve tracking of who did what, we follow the Linux Kernel's
27+
["sign your work" system](https://github.com/wking/signed-off-by).
28+
This is also called a
29+
["DCO" or "Developer's Certificate of Origin"](https://developercertificate.org/).
30+
31+
**All** commits are required to include this sign off and we use the
32+
[Probot DCO App](https://github.com/probot/dco) to check pull requests for
33+
this.
34+
35+
The sign-off is a simple line at the end of the explanation for the
36+
patch, which certifies that you wrote it or otherwise have the right to
37+
pass it on as a open-source patch. The rules are pretty simple: if you
38+
can certify the below:
39+
40+
Developer's Certificate of Origin 1.1
41+
42+
By making a contribution to this project, I certify that:
43+
44+
(a) The contribution was created in whole or in part by me and I
45+
have the right to submit it under the open source license
46+
indicated in the file; or
47+
48+
(b) The contribution is based upon previous work that, to the best
49+
of my knowledge, is covered under an appropriate open source
50+
license and I have the right under that license to submit that
51+
work with modifications, whether created in whole or in part
52+
by me, under the same open source license (unless I am
53+
permitted to submit under a different license), as indicated
54+
in the file; or
55+
56+
(c) The contribution was provided directly to me by some other
57+
person who certified (a), (b) or (c) and I have not modified
58+
it.
59+
60+
(d) I understand and agree that this project and the contribution
61+
are public and that a record of the contribution (including all
62+
personal information I submit with it, including my sign-off) is
63+
maintained indefinitely and may be redistributed consistent with
64+
this project or the open source license(s) involved.
65+
66+
then you just add a line saying
67+
68+
Signed-off-by: Random J Developer <[email protected]>
69+
70+
using your real name (sorry, no pseudonyms or anonymous contributions.)
71+
72+
73+
74+
75+
76+
77+
----
78+
79+
This file is generated from [README.md](README.md), please edit that file then
80+
run the `./.update-contributing.py`.
81+

‎COPYING

+13
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
Copyright (C) 2018 The Project Trellis Authors. All rights reserved.
2+
3+
Permission to use, copy, modify, and/or distribute this software for any
4+
purpose with or without fee is hereby granted, provided that the above
5+
copyright notice and this permission notice appear in all copies.
6+
7+
THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
8+
WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
9+
MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
10+
ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
11+
WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
12+
ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
13+
OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

‎README.md

+196
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,196 @@
1+
# Project Trellis
2+
3+
Documenting the Lattice ECP5 bit-stream format.
4+
5+
This repository contains both tools and scripts which allow you to document the
6+
bit-stream format of Lattice ECP5 series FPGAs.
7+
8+
More documentation can be found published on
9+
[prjtrellis ReadTheDocs site](http://prjtrellis.readthedocs.io/en/latest/) -
10+
this includes;
11+
* FIXME(@tinyfpga): Make these documents.
12+
* [Highlevel Bitstream Architecture](http://prjtrellis.readthedocs.io/en/latest/architecture/overview.html)
13+
* [Overview of DB Development Process](http://prjrellis.readthedocs.io/en/latest/db_dev_process/overview.html)
14+
15+
This follows follows the lead of
16+
[Project X-Ray](https://github.com/SymbiFlow/prjxray) - which is documenting
17+
the bitstream format for the Xilinx Series 7 devices.
18+
19+
# Quickstart Guide
20+
21+
Install XXXXX
22+
FIXME(@tinyfpga): Put instructions here.
23+
24+
Pull submodules:
25+
26+
git submodule update --init --recursive
27+
28+
Get a head start by downloading current database:
29+
30+
# Give the argument;
31+
# - https if you to use the https protocol (default)
32+
# - git+ssh if you want to use git+ssh protocol
33+
# - git if you want to use the git protocol
34+
./download-latest-db.sh
35+
36+
Always make sure to set the environment for the device you are working on before
37+
running any other commands:
38+
39+
source database/XXXXXX/settings.sh
40+
41+
Creating HTML documentation:
42+
43+
cd htmlgen
44+
python3 htmlgen.py
45+
46+
(Re-)creating the database:
47+
48+
cd fuzzers
49+
make -j$(nproc)
50+
51+
(Re-)creating parts of the database, for example LUT init bits:
52+
53+
cd fuzzers/010-lutinit
54+
make -j$(nproc) run
55+
56+
# Process
57+
58+
The documentation is done through a "black box" process were XXXXX is asked to
59+
generate a large number of designs which then used to create bitstreams. The
60+
resulting bit streams are then cross correlated to discover what different bits
61+
do.
62+
63+
This follows the same process as
64+
[Project X-Ray](https://github.com/SymbiFlow/prjxray) -
65+
[more documentation can be found here](https://prjxray.readthedocs.org).
66+
67+
## Parts
68+
69+
### [Minitests](minitests)
70+
71+
There are also "minitests" which are designs which can be viewed by a human in
72+
Vivado to better understand how to generate more useful designs.
73+
74+
### [Experiments](experiments)
75+
76+
Experiments are like "minitests" except are only useful for a short period of
77+
time. Files are committed here to allow people to see how we are trying to
78+
understand the bitstream.
79+
80+
When an experiment is finished with, it will be moved from this directory into
81+
the latest "prjxray-experiments-archive-XXXX" repository.
82+
83+
### [Fuzzers](fuzzers)
84+
85+
Fuzzers are the scripts which generate the large number of bitstream.
86+
87+
They are called "fuzzers" because they follow an approach similar to the
88+
[idea of software testing through fuzzing](https://en.wikipedia.org/wiki/Fuzzing).
89+
90+
### [Tools](tools) & [Libs](libs)
91+
92+
Tools & libs are useful tools (and libraries) for converting the resulting
93+
bitstreams into various formats.
94+
95+
Binaries in the tools directory are considered more mature and stable then
96+
those in the [utils](utils) directory and could be actively used in other
97+
projects.
98+
99+
### [Utils](utils)
100+
101+
Utils are various tools which are still highly experimental. These tools should
102+
only be used inside this repository.
103+
104+
### [Third Party](third_party)
105+
106+
Third party contains code not developed as part of Project X-Ray.
107+
108+
109+
# Database
110+
111+
Running the all fuzzers in order will produce a database which documents the
112+
bitstream format in the [database](database) directory.
113+
114+
# Current Focus
115+
116+
FIXME(@tinyfgpa): Put details here.
117+
118+
The aim is to eventually document all parts in the Lattice ECP5 series FPGAs
119+
but we can not do this alone, **we need your help**!
120+
121+
122+
## TODO List
123+
124+
- [ ] Write a TODO list
125+
126+
127+
# Contributing
128+
129+
There are a couple of guidelines when contributing to Project Trellis which are
130+
listed here.
131+
132+
### Sending
133+
134+
All contributions should be sent as
135+
[GitHub Pull requests](https://help.github.com/articles/creating-a-pull-request-from-a-fork/).
136+
137+
### License
138+
139+
All code in the Project X-Ray repository is licensed under the very permissive
140+
[ISC Licence](COPYING). A copy can be found in the [`COPYING`](COPYING) file.
141+
142+
All new contributions must also be released under this license.
143+
144+
### Code of Conduct
145+
146+
By contributing you agree to the [code of conduct](CODE_OF_CONDUCT.md). We
147+
follow the open source best practice of using the [Contributor
148+
Covenant](https://www.contributor-covenant.org/) for our Code of Conduct.
149+
150+
### Sign your work
151+
152+
To improve tracking of who did what, we follow the Linux Kernel's
153+
["sign your work" system](https://github.com/wking/signed-off-by).
154+
This is also called a
155+
["DCO" or "Developer's Certificate of Origin"](https://developercertificate.org/).
156+
157+
**All** commits are required to include this sign off and we use the
158+
[Probot DCO App](https://github.com/probot/dco) to check pull requests for
159+
this.
160+
161+
The sign-off is a simple line at the end of the explanation for the
162+
patch, which certifies that you wrote it or otherwise have the right to
163+
pass it on as a open-source patch. The rules are pretty simple: if you
164+
can certify the below:
165+
166+
Developer's Certificate of Origin 1.1
167+
168+
By making a contribution to this project, I certify that:
169+
170+
(a) The contribution was created in whole or in part by me and I
171+
have the right to submit it under the open source license
172+
indicated in the file; or
173+
174+
(b) The contribution is based upon previous work that, to the best
175+
of my knowledge, is covered under an appropriate open source
176+
license and I have the right under that license to submit that
177+
work with modifications, whether created in whole or in part
178+
by me, under the same open source license (unless I am
179+
permitted to submit under a different license), as indicated
180+
in the file; or
181+
182+
(c) The contribution was provided directly to me by some other
183+
person who certified (a), (b) or (c) and I have not modified
184+
it.
185+
186+
(d) I understand and agree that this project and the contribution
187+
are public and that a record of the contribution (including all
188+
personal information I submit with it, including my sign-off) is
189+
maintained indefinitely and may be redistributed consistent with
190+
this project or the open source license(s) involved.
191+
192+
then you just add a line saying
193+
194+
Signed-off-by: Random J Developer <[email protected]>
195+
196+
using your real name (sorry, no pseudonyms or anonymous contributions.)

0 commit comments

Comments
 (0)