1===================== 2How to add a new chip 3===================== 4 5To add a new chip definition you need to send a patch to flashrom. This can be your first patch to flashrom. However if it is 6your first patch please read carefully :doc:`/dev_guide/development_guide`, and set up dev environment locally. 7 8The expectation is that you have tested successfully at least some of the operations on the chip (not necessarily all of them). 9There is an exception: when datasheet covers more than one model of the same chip, but you only have one and tested that one. 10Typically, you would add all the models covered by the datasheet you have, but only mark tested the one you tested. 11 12To begin with, make sure you have a link to the publicly available datasheet for the chip you want to add. Publicly 13available datasheet is a requirement for adding a new chip. 14 15Open the datasheet, ``flashchips.c`` and ``include/flashchips.h``, and then 16 17Model ID and vendor ID 18====================== 19 20Find model ID and vendor ID in the datasheet. This information often can be found in the sections like "Device identification", 21"Device ID", "Manufacturer ID", "Table of ID definitions" or something similar to that. 22These values come in combination with commands used for probing the chip (more on probing below). Most commonly used command for 23probing SPI chips is ``0x9f`` which corresponds to ``PROBE_SPI_RDID``. 24 25At this point you need to double-check if exact same chip is already defined. Search for the ``.name`` and ``.vendor`` of the chip 26you have in ``flashchips.c`` and if found, compare values of ``.manufacture_id`` and ``.model_id``. If all 4 values match, it 27seems like the chip already defined. In this case you can try using it. Possibly, only the testing status of the chip needs to be 28updated, in this case see :doc:`how_to_mark_chip_tested` for instructions. 29 30Vendor (manufacturer) ID 31------------------------ 32 33Search for vendor ID in ``include/flashchips.h``, IDs are defined as macros. If it exists already, use existing macro in your 34chip definition. If it does not exist (which means your chip is the first ever for this vendor), define macro for this ID, 35add a comment. Look at existing IDs in ``include/flashchips.h`` as examples. 36 37Model ID 38-------- 39 40Search for model ID in ``include/flashchips.h``. If there is no macro defined for it, add macro for model ID in the corresponding 41section for given vendor. 42 43Model IDs should follow the pattern. They are all uppercase; first the manufacturer name (used for the manufacturer IDs macros 44on top of each paragraph in flashchips.h), followed by an underscore and then the chipname. The latter should in general equal 45the ``.name``, with dots (and other disallowed characters) replaced by underscores. Shared chip IDs typically use the macro name 46that happened to be added first to flashrom (which is also probably the first one manufactured) and which usually matches 47the other chips of that series in ``include/flashchips.h``. 48 49If you added a new model ID, use it in new chip definition, skip the rest of instructions about Model ID 50and continue with the next section "Properties". 51 52Model ID already exists 53^^^^^^^^^^^^^^^^^^^^^^^ 54 55It is possible that model ID already exists in the header. Then find the corresponding definition in ``flashchips.c`` and inspect 56it carefully. Is it the same chip that you have or a different one? 57 58The question you need to figure out is: whether existing definition can work for your chip or not. You figure that out by 59reading the rest of instructions and comparing the values from the datasheet with existing definition. 60 61Existing definition matches, but it has a different chip name 62^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 63 64It is possible all the values from the datasheet match existing definition, but it has a different chip name. This is fine, 65and in this case you need to add a comment to the macro ID definition which looks like ``Same as ...``. 66Look at existing examples in ``include/flashchips.h`` file. 67You should change the ``.name`` to reflect the additional chip model (see other chips of naming examples). 68You don't need to add new definition. 69 70Existing definition does not match 71^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 72 73It is possible that, despite of the same model ID, existing vs new chips have significant different and they 74need different definitions. Judging the significance of a difference might be not trivial and might require some understanding 75of flashrom behavior, however the examples of significant differences are: different sizes of erase blocks, 76or different opcodes for operations (see more on operations below), or different configuration for write-protection (if this 77config is defined). 78 79In this case you need to do both: 80 81* Add a comment to existing model ID macro, ``Same as ...`` 82* Add new chip definition, re-use existing ID macro 83 84Note that if you need to add new chip definition, it is fine to copy a similar one that already exist and correct the values. 85 86Make sure to keep the alphabetic ordering of chip names, and place new definition into the section with other chips 87by the same vendor. 88 89Properties 90========== 91 92* From the datasheet, get ``.vendor``, ``.name``, ``.bustype``, ``.total_size``. 93* ``.voltage`` defines the upper and lower bounds of the supply voltage of the chip. If there are multiple chip models 94 with different allowed voltage ranges, the `intersection <https://en.wikipedia.org/wiki/Intersection_(set_theory)>`_ 95 should be used and an appropriate comment added. 96* ``.page_size`` is really hard. 97 Please read this `long explanation <https://mail.coreboot.org/pipermail/flashrom/2013-April/010817.html>`_, 98 or ignore it for now and set it to 256. 99* ``.tested`` is used to indicate if the code was tested to work with real hardware, its possible values are defined 100 in ``include/flash.h``. Without any tests it should be set to ``TEST_UNTESTED``. 101 See also another doc :doc:`how_to_mark_chip_tested`. 102 103Feature Bits 104============ 105 106We encode various features of flash chips in a bitmask named ``.feature_bits``. 107Available options can be found in ``include/flash.h``, look for macros defined by the pattern ``#define FEATURE_XXX``. 108 109Some of the feature bits have more detailed docs, see below. 110 111Write-Status-Register (WRSR) Handling 112------------------------------------- 113 114The Write Status Register (WRSR) is used exclusively in SPI flash chips to configure various settings within the flash chip, 115including write protection and other features. 116The way WRSR is accessed varies between SPI flash chips, leading to the need for these feature bits. 117 118* ``FEATURE_WRSR_EWSR`` 119 indicates that we need an **Enable-Write-Status-Register** (EWSR) instruction which opens the status register for the 120 immediately-followed next WRSR instruction. Usually, the opcode is **0x50**. 121 122* ``FEATURE_WRSR_WREN`` 123 indicates that we need an **Write-Enable** (WREN) instruction to set the Write Enable Latch (WEL) bit. The WEL bit 124 must be set prior to every WRSR command. Usually, the opcode is **0x06**. 125 126* ``FEATURE_WRSR_EITHER`` 127 indicates that either EWSR or WREN is supported in this chip. 128 129Operations 130========== 131 132Each operation is defined as a enum value from a corresponding enum. 133 134Probe 135----- 136 137``.probe`` indicates which function is called to fetch IDs from the chip and to compare them with the ones in 138``.manufacture_id`` and ``.model_id``. For most SPI flash chips ``PROBE_SPI_RDID`` is the most commonly used if the datasheets 139mentions **0x9f** as an identification/probing opcode. 140 141To see the full list of available probing functions, check definition of ``enum probe_func`` in ``include/flash.h``. 142You may need to inspect the source code of what a probing function is doing, check the mapping ``lookup_probe_func_ptr`` and 143search for the function code. 144 145``.probe_timing`` is only used for non-SPI chips. It indicates the delay after "enter/exit ID mode" commands in microseconds 146(see ``include/flash.h`` for special values). 147 148Read and write 149-------------- 150 151``.read`` and ``.write`` indicate which functions are used for reading and writing on the chip. Currently flashrom 152does only support a single function each. The one that is best supported by existing programmers should be used for now, 153but others should be noted in a comment if available. 154 155To see the full list of available functions, check definitions of ``enum read_func`` and ``enum write_func`` in ``include/flash.h``. 156To inspect the source code, check the mappings ``lookup_write_func_ptr`` and ``lookup_read_func_ptr`` and search for 157the function code. 158 159The write granularity can be expressed by the ``.gran`` field. If you think you need something else than the default 160``write_gran_256bytes`` then you should definitely ask one of the regular flashrom hackers first. 161Possible values can be found in ``include/flash.h``. 162 163Erase 164----- 165 166``block_erasers`` stores an array of pairs of erase functions (``.block_erase``) with their respective layout (``.eraseblocks``). 167 168``.block_erase`` is similar to the probing function. You should at least check that the opcode named in the function name 169is matching the respective opcode in the datasheet. 170 171To see the full list of available functions, check definition of ``enum block_erase_func`` in ``include/flash.h``. 172To inspect the source code, check the mappings ``lookup_erase_func_ptr`` and search for the function code. 173 174Two forms of ``.eraseblocks`` can be distinguished: symmetric and asymmetric layouts. 175Symmetric means that all blocks that can be erased by an opcode are sized equal. In that case a single range can define 176the whole layout (e.g. ``{4 * 1024, 256}`` means 256 blocks of 4 kB each). Asymmetric layouts on the other hand contain 177differently sized blocks, ordered by their base addresses (e.g. ``{{8 * 1024, 1}, {4 * 1024, 2}, {16 * 1024, 7}}`` describes 178a layout that starts with a single 8 kB block, followed by two 4 kB blocks and 7 16 kB blocks at the end). 179 180``.eraseblocks`` should be listed in order, from the smallest to the largest size. 181 182Printlock 183--------- 184 185``.printlock`` is a `misnomer to some extent <https://mail.coreboot.org/pipermail/flashrom/2011-May/006495.html>`_. 186 187It is used not only to print (write) protected address ranges of the chip, but also to pretty print the values 188of the status register(s) - especially true for SPI chips. There are a lot of existing functions for that already 189and you should reuse one if possible. Comparing the description of the status register in the datasheet of an already 190supported chip with that of your chip can help to determine if you can reuse a printlock function. 191 192Check for definition of ``enum printlock_func`` and ``lookup_printlock_func_ptr`` for available options and source code. 193 194Unlock 195------ 196 197``.unlock`` is called before flashrom wants to modify the chip's contents to disable possible write protections. 198It is related to the ``.printlock`` function as it tries to change some of the bits displayed by ``.printlock``. 199 200Check for definition of ``enum blockprotect_func`` and ``lookup_blockprotect_func_ptr`` for available options and source code. 201 202Write-protection 203================ 204 205Write-protection support is optional, and if you haven't tested it on the chip, don't add it. 206If you, however, used and tested it, that would be great to add to chip definition. 207 208Registers bits 209-------------- 210 211``.reg_bits`` stores information about what configuration bits the chip has and where they are found. 212 213For example, ``.cmp = {STATUS2, 6, RW}`` indicates that the chip has a complement bit (``CMP``) and it is the 6th bit 214of the 2nd status register. See ``struct reg_bit_info`` in ``include/flash.h`` for details on each of the structure's fields. 215 216Note that some chips have configuration bits that function like ``TB/SEC/CMP`` but are called something else in the datasheet 217(e.g. ``BP3/BP4/...``). These bits should be assigned to a field *according their function* and the datasheet name should be 218noted in a comment, for example: 219 220:code:`.sec = {STATUS1, 6, RW}, /* Called BP4 in datasheet, acts like SEC */` 221 222Decode range 223------------ 224 225``.decode_range`` points to a function that determines what protection range will be selected by particular configuration 226bit values. It is required for write-protect operations on the chip. 227 228Check for definition of ``enum decode_range_func`` and ``lookup_decode_range_func_ptr`` for available options and source code. 229 230Test your changes 231================= 232 233After making changes in the code, rebuild flashrom, run unit tests, and test the chip. 234 235Add testing information to commit message. 236 237When all of the above done, follow :doc:`/dev_guide/development_guide` to push a patch and go through review process. 238Dev guide has more details on the process. 239