Easy projects: Difference between revisions

From flashrom
Jump to navigation Jump to search
No edit summary
 
(32 intermediate revisions by 5 users not shown)
Line 1: Line 1:
You probably came here trying to find a small (minutes to hours) and easy task where you can get your hands dirty and get results immediately.
This page is listing small projects for the beginners, to start learning about flashrom development and do some useful tasks.


If you're a coreboot or flashrom newbie, this page is for you.
If you're a flashrom newbie, this page is for you.


= flashrom =
= Open tasks =


The [[flashrom]] tool can read/write coreboot/BIOS images from/to flash chips.
Important note: every task in easy projects has a topic. If you send a patch for one of the projects, please add a topic to your gerrit patch. Before sending a patch, have a look at currently open patches for the same topic, to avoid accidentally duplicating someone else's effort.


== Add timing info to flash chip definitions ==
We've had situations when two contributors sent patches for the same thing (without knowing about each other), and situations like that are usually stressful and not easily resolved. Please look for patches under the topic, and add a topic to your own patches.


Go through the list of flash chips in flashchips.c inside the flashrom source. For each chip (except SPI chips), read through the data sheets and add a comment to the flash chip definition which contains the timing information in microseconds(!) for the probe sequence.
Topic can be added when pushing the patch, for example <tt>git push upstream HEAD:refs/for/master%topic=easy_projects_unit_tests</tt>. Alternatively topic can be added on Gerrit UI.


This will make probing a lot more reliable.
== Write a unit test ==
Topic: easy_projects_unit_test


Every annotated chip helps.
Unit tests are located under tests/ directory in the tree. Have a look at existing tests, and think of what you can add. The test for easy projects can be small. Hint: it is easier to add a test scenario for the area that already has tests (for example new scenario for programmer lifecycle, given that the programmer has some tests). It is harder to write a test for the programmer that has no tests at all.


== Add the bus type to flash chip definitions ==
== Take a bug in a bugtracker ==
Topic: easy_projects_bugtracker


Go through the list of flash chips in flashchips.c inside the flashrom source. Look for chip definitions which have .bustype = CHIP_BUSTYPE_NONSPI and look at their data sheets. Read the data sheets and try to figure out the flash bus they use (Parallel/LPC/FWH/SPI). Change the bustype field to CHIP_BUSTYPE_PARALLEL etc. and post a patch to the list.
We have an "Easy projects" category in our bugtracker, and you can take a bug from there.
List of bugs in the category can be found by the [[https://ticket.coreboot.org/projects/flashrom/issues?utf8=%E2%9C%93&set_filter=1&sort=id%3Adesc&f%5B%5D=status_id&op%5Bstatus_id%5D=o&f%5B%5D=category_id&op%5Bcategory_id%5D=%3D&v%5Bcategory_id%5D%5B%5D=16&f%5B%5D=&c%5B%5D=tracker&c%5B%5D=status&c%5B%5D=priority&c%5B%5D=category&c%5B%5D=subject&c%5B%5D=assigned_to&c%5B%5D=updated_on&group_by=&t%5B%5D link]]


This will make probing faster and more reliable.
== Fix issues found by scan-build ==
Topic: easy_project_scan_build


Even a single updated chip helps.
Run scan-build in the tree:


[[Flashrom#Communication_bus_protocol]] has a writeup on how to figure out the bus type.
<tt>make clean && CFLAGS='-fsanitize=leak' scan-build make</tt>


== Add new flash chip definitions ==
At the moment of writing this, it produces around 30 issues, which means there are plenty of easy projects.


We have a few dozen chip IDs listed in flash.h, but not in flashchips.c. Find them, dig up the data sheets and add chip definitions for them to flashchips.c. You can use similar flash chips as a guideline.
In general, one issue == one Easy project. However, you can fix more than one issue in the same patch if there are multiple occurrences of the same issue in the same file.


This will reduce the number of undetected chips.
You need to install clang-tools for this project.


Every added chip broadens flashrom support.
== Find chips without voltage data ==
Topic: easy_project_chips_voltage


== Test flashrom ==
We have added allowed supply voltage ranges (usually denoted VCC in datasheets) to the chip definitions in flashchips.c, but not all of them.
Complete the list by looking for the right datasheet and editing flashchips.c accordingly.


If you have a desktop (no laptops/notebooks/netbooks), please run
== Find boards that have a board enable but are not mentioned in print.c ==
flashrom
Topic: easy_projects_boards
and check if it finds your flash chip. If it does and any of the operations are listed as unsupported, we'd like to hear about it. If your flash chip is not found, we'd like to hear about it as well.


In both cases, please send the output of
There may be a few boards that had a [[Board Enable]] added (in board_enable.c) but which were not added to the array named boards_known in print.c (usually by mistake).
flashrom -V
to the coreboot [[Mailinglist|mailing list]] (preferred) or to [mailto:flashrom@coreboot.org flashrom@coreboot.org]


= coreboot =
Find those and send a list or even a patch for print.c to the mailing list.


I'll skip explaining what coreboot is. The whole wiki is about this topic and I can't summarize it in one sentence.
Even better would be an automatic detection of such mistakes.
We already do some sanity checks on startup (cf. <tt>selfcheck()</tt> in <tt>flashrom.c</tt>).


== coreboot v2 ==
== Add timing info to flash chip definitions (mostly done) ==
Topic: easy_project_chip_timing


The workhorse version of coreboot. Lots of supported boards, but difficult to work with.
Go through the list of flash chips in flashchips.c inside the flashrom source. For each chip (except SPI chips), read through the data sheets and add a comment to the flash chip definition which contains the timing information in microseconds(!) for the probe sequence.


===AMD 740G information gathering===
This will make probing a lot more reliable.
(This project description is not finished yet)


If you have a board with AMD 740G chipset, please run (as root)
Every annotated chip helps.
flashrom -V
lspci -nnvvvxxxx
superiotool -edV
dmidecode
and mail the output to the [[Mailinglist|coreboot mailing list]] together with the exact model number/name of your board.


This helps us evaluate which boards are good targets for coreboot.
== Add new flash chip definitions ==
Topic: easy_project_new_chip


Here are some boards:
We have a few dozen chip IDs listed in flash.h, but not in flashchips.c. You can find them by running '''util/list_yet_unsupported_chips.sh'''. Then dig up the data sheets and add chip definitions for them to flashchips.c. You can use similar flash chips as a guideline. Check our list of pending patches (http://patchwork.coreboot.org/project/flashrom/list/) to not duplicate someone's work. Reviewing any pending patches by verifying the values in the patches is of course also very welcomed too! The process of adding a chip and the needed data structures are explained [[Development_Guidelines#Adding.2Freviewing_a_new_flash_chip|here]].
http://www.czechcomputer.cz/cat_tree.jsp?bpath=Z%C3%A1kladn%C3%AD+desky\Socket+AM2%2B\AMD+740G


== coreboot v3 ==
This will reduce the number of undetected chips and every added chip broadens flashrom support.


The next generation version of coreboot. Few supported boards, still in the design testing phase, easy to work with.
== Add (ferroelectric, F-RAM) SPI chips made by Cypress / Ramtron ==
Topic: easy_project_cypress_ramtron


TODO: Add easy tasks here.
http://www.cypress.com/products/f-ram-serial


= Payloads =
Example datasheet: http://www.cypress.com/file/41676/download


coreboot can use a number of different [[Payloads|payloads]].
These work mostly like SPI flashes, except for (these are just the biggest points):
* No erase command (or erasing necessary)
* 2-byte addresses (atleast for smaller/older devices)


== Add/test new supported payloads ==
== Test flashrom ==
Topic: easy_project_test_flashrom


* Test syslinux (probably requires [[SeaBIOS]] in addition, needs to be checked).
Please see the [[Board Testing HOWTO]].
* Port [[GPXE]] to "native" coreboot (it works fine together with [[SeaBIOS]] though).


= Other =
== Replace programmer_delay() with internal_sleep() where appropriate ==
Topic: easy_project_delay


* Add [http://tracker.coreboot.org/trac/coreboot/ticket/95 support for using coreboot in VirtualBox].
If a delay call does not depend on precise timing and if the '''programmer''' in question '''does not offer its own delay function''', programmer_delay() can be replaced with internal_sleep().
If a delay call does not depend on precise timing and if the delay '''should run on the host''', programmer_delay() can be replaced with internal_sleep().

Latest revision as of 10:39, 3 March 2023

This page is listing small projects for the beginners, to start learning about flashrom development and do some useful tasks.

If you're a flashrom newbie, this page is for you.

Open tasks

Important note: every task in easy projects has a topic. If you send a patch for one of the projects, please add a topic to your gerrit patch. Before sending a patch, have a look at currently open patches for the same topic, to avoid accidentally duplicating someone else's effort.

We've had situations when two contributors sent patches for the same thing (without knowing about each other), and situations like that are usually stressful and not easily resolved. Please look for patches under the topic, and add a topic to your own patches.

Topic can be added when pushing the patch, for example git push upstream HEAD:refs/for/master%topic=easy_projects_unit_tests. Alternatively topic can be added on Gerrit UI.

Write a unit test

Topic: easy_projects_unit_test

Unit tests are located under tests/ directory in the tree. Have a look at existing tests, and think of what you can add. The test for easy projects can be small. Hint: it is easier to add a test scenario for the area that already has tests (for example new scenario for programmer lifecycle, given that the programmer has some tests). It is harder to write a test for the programmer that has no tests at all.

Take a bug in a bugtracker

Topic: easy_projects_bugtracker

We have an "Easy projects" category in our bugtracker, and you can take a bug from there. List of bugs in the category can be found by the [link]

Fix issues found by scan-build

Topic: easy_project_scan_build

Run scan-build in the tree:

make clean && CFLAGS='-fsanitize=leak' scan-build make

At the moment of writing this, it produces around 30 issues, which means there are plenty of easy projects.

In general, one issue == one Easy project. However, you can fix more than one issue in the same patch if there are multiple occurrences of the same issue in the same file.

You need to install clang-tools for this project.

Find chips without voltage data

Topic: easy_project_chips_voltage

We have added allowed supply voltage ranges (usually denoted VCC in datasheets) to the chip definitions in flashchips.c, but not all of them. Complete the list by looking for the right datasheet and editing flashchips.c accordingly.

Find boards that have a board enable but are not mentioned in print.c

Topic: easy_projects_boards

There may be a few boards that had a Board Enable added (in board_enable.c) but which were not added to the array named boards_known in print.c (usually by mistake).

Find those and send a list or even a patch for print.c to the mailing list.

Even better would be an automatic detection of such mistakes. We already do some sanity checks on startup (cf. selfcheck() in flashrom.c).

Add timing info to flash chip definitions (mostly done)

Topic: easy_project_chip_timing

Go through the list of flash chips in flashchips.c inside the flashrom source. For each chip (except SPI chips), read through the data sheets and add a comment to the flash chip definition which contains the timing information in microseconds(!) for the probe sequence.

This will make probing a lot more reliable.

Every annotated chip helps.

Add new flash chip definitions

Topic: easy_project_new_chip

We have a few dozen chip IDs listed in flash.h, but not in flashchips.c. You can find them by running util/list_yet_unsupported_chips.sh. Then dig up the data sheets and add chip definitions for them to flashchips.c. You can use similar flash chips as a guideline. Check our list of pending patches (http://patchwork.coreboot.org/project/flashrom/list/) to not duplicate someone's work. Reviewing any pending patches by verifying the values in the patches is of course also very welcomed too! The process of adding a chip and the needed data structures are explained here.

This will reduce the number of undetected chips and every added chip broadens flashrom support.

Add (ferroelectric, F-RAM) SPI chips made by Cypress / Ramtron

Topic: easy_project_cypress_ramtron

http://www.cypress.com/products/f-ram-serial

Example datasheet: http://www.cypress.com/file/41676/download

These work mostly like SPI flashes, except for (these are just the biggest points):

  • No erase command (or erasing necessary)
  • 2-byte addresses (atleast for smaller/older devices)

Test flashrom

Topic: easy_project_test_flashrom

Please see the Board Testing HOWTO.

Replace programmer_delay() with internal_sleep() where appropriate

Topic: easy_project_delay

If a delay call does not depend on precise timing and if the programmer in question does not offer its own delay function, programmer_delay() can be replaced with internal_sleep(). If a delay call does not depend on precise timing and if the delay should run on the host, programmer_delay() can be replaced with internal_sleep().