|
|
| (57 intermediate revisions by 6 users not shown) |
| Line 1: |
Line 1: |
| = Patch submission =
| | {{#externalredirect: https://www.flashrom.org/dev_guide/development_guide.html }} |
| | |
| The following guidelines are for [http://www.coreboot.org/ coreboot], but most of them apply to flashrom as well: [http://www.coreboot.org/Development_Guidelines coreboot development guidelines]. The really important part is about the [http://www.coreboot.org/Development_Guidelines#Sign-off_Procedure Signed-off-by procedure].
| |
| | |
| We try to '''reuse as much code as possible''' and create new files only if absolutely needed, so if you find a function somewhere in the tree which already does what you want (even if it is for a totally different chip), please use it. Most chips work fine with probe_jedec() even if the command sequence seems to differ at first glance. See also [[Random notes#Command_set_secrets|Command set secrets]].
| |
| | |
| The '''patch reviews''' may sound harsh, but please don't get discouraged. We try to merge simple patches after one or two iterations and complicated ones after a maximum of three iterations.
| |
| | |
| If you introduce new features (not flash chips, but stuff like partial programming, support for new external programmers, voltage handling, etc) please '''discuss your plans''' on the [[Mailinglist|mailing list]] first. That way, we can avoid duplicated work and know about how flashrom internals need to be adjusted and you avoid frustration if there is some disagreement about the design.
| |
| | |
| For patches that modify convoluted tables like <tt>struct flashchip flashchips[]</tt> in flashchips.c it may make sense to increase the lines of '''context''' to include enough information directly in the patch for reviewers (for example to include the chip names when changing other parameters like .voltage). To do this with subversion use '''svn diff --diff-cmd diff -x -u5'''; or with git use '''git format-patch -U5''' where 5 is an example for the number of lines of context you want.
| |
| | |
| = Recurring Tasks =
| |
| == Adding/reviewing a new flash chip ==
| |
| # Get the datasheet of the exact type of chip.
| |
| # Open <tt>flashchips.c</tt> and <tt>flashchips.h</tt>.
| |
| # First, find the best* IDs in the datasheet (*FIXME: this needs to be explained together with the probing somewhere else in detail) and check if the ID exists in <tt>flashchips.h</tt> already
| |
| #* If it does but is named after a different chip,
| |
| #*:then add a comment regarding the twin and continue by comparing the definition in <tt>flashchips.c</tt> with the datasheet of the twin/new chip as if you would add it but leave out the next step (see below). First you should change the <tt>.name</tt> to reflect the additional chip model (see other chips of naming examples). If you find significant* differences in the chips behavior you have found a so called evil twin (*judging the significance of a difference is quite hard and requires some understanding of flashrom behavior, examples of significant differences are: different sizes of blocks or different opcodes for operations). In that case copy the entry and continue to change that (don't forget to undo the previous changes before).
| |
| #* If it does and the name matches too,
| |
| #*:the chip is either already added or only the ID was added and you should use that define.
| |
| #* If it does not,
| |
| #*:then you should add it conforming to the standards/comments in the file.
| |
| #: Usually the chip IDs follow a simple scheme: They are all uppercase; first the manufacturer name (like for the manufacturer IDs on top of each paragraph in flashchips.h) followed by an underscore and then the chipname. The latter should in general equal the <tt>.name</tt>, with dots (and other disallowed characters) replaced by underscores. Shared chip IDs typically use the macro name that happened to be added first to flashrom (which is also probably the first one manufactured) and which usually matches the other chips of that series in flashchips.h. | |
| # If possible copy an existing, similar entry in the giant array in <tt>flashchips.c</tt> or start a new one at the right position (according to the comment on top of the array)
| |
| # Add <tt>.vendor</tt>, <tt>.name</tt>, IDs selected as explained above and <tt>.total_size</tt>.
| |
| # <tt>.page_size</tt> is really hard. Please read this [http://www.flashrom.org/pipermail/flashrom/2013-April/010817.html long explanation], or ignore it for now and set it to <tt>256</tt>.
| |
| # We encode various features of flash chips in a bitmask named <tt>.feature_bits</tt>. The various possibilities can be found in <tt>flash.h</tt>.
| |
| # <tt>.tested</tt> is used to indicate if the code was tested to work with real hardware, its possible values are defined in <tt>flash.h</tt>. Without any tests it should be set to <tt>TEST_UNTESTED</tt>.
| |
| # <tt>.probe</tt> indicates which function is called to fetch IDs from the chip and to compare them with the ones in <tt>.manufacture_id</tt> and <tt>.model_id</tt>. This requires some knowledge or source reading. For most SPI flash chips <tt>probe_spi_rdid</tt> is the right one if the datasheets mentions <tt>0x9f</tt> as an identification/probing opcode.
| |
| # <tt>.probe_timing</tt> is only used for non-SPI chips. It indicates the delay after "enter/exit ID mode" commands in microseconds (see <tt>flash.h</tt> for special values).
| |
| # <tt>.block_erasers</tt> stores an array of pairs of erase functions (<tt>.block_erase</tt>) with their respective layout (<tt>.eraseblocks</tt>).
| |
| ## <tt>.block_erase</tt> is similar to the probing function. You should at least check that the opcode named in the function name is matching the respective opcode in the datasheet.
| |
| ## Two forms of <tt>.eraseblocks</tt> can be distinguished: symmetric and asymmetric layouts. Symmetric means that all blocks that can be erased by an opcode are sized equal. In that case a single range can define the whole layout (e.g. <tt>{4 * 1024, 256}</tt> means 256 blocks of 4 kB each). Asymmetric layouts on the other hand contain differently sized blocks, ordered by their base addresses (e.g. <tt>{{8 * 1024, 1}, {4 * 1024, 2}, {16 * 1024, 7}}</tt> describes a layout that starts with a single 8 kB block, followed by two 4 kB blocks and 7 16 kB blocks at the end).
| |
| # <tt>.printlock</tt> is a [http://www.flashrom.org/pipermail/flashrom/2011-May/006495.html misnomer to some extent]. It is misused not only to print (write) protected address ranges of the chip, but also to pretty print the values of the status register(s) - especially true for SPI chips. There are a lot of existing functions for that already and you should reuse one if possible. Comparing the description of the status register in the datasheet of an already supported chip with that of your chip can help to determine if you can reuse a printlock function.
| |
| # <tt>.unlock</tt> is called before flashrom wants to modify the chip's contents to disable possible write protections. It is tightly related to the <tt>.printlock</tt> function as it tries to change some of the bits displayed by <tt>.printlock</tt>.
| |
| # <tt>.write</tt> and <tt>.read</tt> are function pointers with the obvious meaning. Currently flashrom does only support a single function each. The one that is best supported by existing programmers should be used for now, but others should be noted in a comment if available.
| |
| # <tt>.voltage</tt> defines the upper and lower bounds of the supply voltage of the chip. If there are multiple chip models with different allowed voltage ranges, the [http://en.wikipedia.org/wiki/Intersection_(set_theory) intersection] should be used and an appropriate comment added.
| |
| # The write [http://www.flashrom.org/pipermail/flashrom/2013-April/010817.html granularity] can be expressed by the <tt>.gran</tt> field. If you think you need something else than the default (<tt>write_gran_256bytes</tt>) then you should definitely ask one of the regular flashrom hackers first. Possible values can be found in <tt>flash.h</tt>.
| |
| | |
| = Committing =
| |
| | |
| Those with commit rights to the (currently subversion-based) source repository should follow the following rules.
| |
| | |
| * Existence of an Acked-by
| |
| ** Except for compile fixes and marking boards/chips/programmers as OK, you need an ack from someone else.
| |
| ** If the patch is needed by someone who is not an experienced developer, you can get an ack from him/her if it is stuff like board enables, chip support, chipset support, ... (no refactoring, no architectural impact) after he/she has tested the patch.
| |
| ** However, if a patch refactors an interface or changes cosmetics of one of the big tables or changes the command line interface, you should get a review from someone who knows the code well.
| |
| * If you ack something and the sender has commit rights, let him commit unless he asks you to commit.
| |
| * The commit message should meet the same requirements that [http://www.coreboot.org/Development_Guidelines#Repository_Commits coreboot's commit message have].
| |
| * After committing please reply to the mailing thread that contains the patch with at least the revision in the body to notify anyone involved of the commit and document it for references in the future and in patchwork or similar facilities.
| |
| * Don't share your login(s)/password(s) (should be obvious, but sadly it is not for everyone :)
| |