Merge branch 'master' into develop

Signed-off-by: Marek Kasiewicz <[email protected]>

Documentation/coding_style.md → Documentation/contributing/coding_style.md

@@ -530,7 +530,7 @@ than desirable (in fact, they are worse than random typing - an infinite
 number of monkeys typing into GNU emacs would never make a good program).
 
 So, you can either get rid of GNU emacs, or change it to use saner values.
-To do the latter, you can stick the following in your .emacs file: 
+To do the latter, you can stick the following in your .emacs file:
 
 ```lisp
 (defun c-lineup-arglist-tabs-only (ignored)
@@ -834,22 +834,51 @@ subject to this rule. Generally they indicate failure by returning some
 out-of-range result. Typical examples would be functions that return
 pointers; they use NULL or the ERR_PTR mechanism to report failure.
 
-Don't re-invent the kernel macros
-----------------------------------
+Headers and includes
+---------------
 
-The header file include/linux/kernel.h contains a number of macros that
-you should use, rather than explicitly coding some variant of them
-yourself. For example, if you need to calculate the length of an array,
-take advantage of the macro
+Headers should always be included at the top of the file, preferrably in
+alphabetical order. Includes should always use the `#include <file.h>`
+notation, except for rare cases where a file in the same directory that
+is not part of a normal include path gets included (e.g. local headers
+in mainboard directories), which should use `#include "file.h"`. Headers
+that can be included from both assembly files and .c files should keep
+all C code wrapped in `#ifndef __ASSEMBLER__` blocks, including includes
+to other headers that don't follow that provision.
+
+Files should generally include every header they need a definition from
+directly (and not include any unnecessary extra headers). Excepted from
+this are certain headers that intentionally chain-include other headers
+which logically belong to them and are just factored out into a separate
+location for implementation or organizatory reasons. This could be
+because part of the definitions is generic and part SoC-specific (e.g.
+`<gpio.h>` chain-including `<soc/gpio.h>`), architecture-specific (e.g.
+`<device/mmio.h>` chain-including `<arch/mmio.h>`), separated out into
+commonlib[/bsd] for sharing/license reasons (e.g. `<cbfs.h>`
+chain-including `<commonlib/bsd/cbfs_serialized.h>`) or just split out
+to make organizing subunits of a larger header easier. This can also
+happen when certain definitions need to be in a specific header for
+legacy POSIX reasons but we would like to logically group them together
+(e.g. `uintptr_t` is in `<stdint.h>` and `size_t` in `<stddef.h>`, but
+it's nicer to be able to just include `<types.h>` and get all the common
+type and helper function stuff we need everywhere).
+
+The headers `<kconfig.h>`, `<rules.h>` and `<commonlib/bsd/compiler.h>`
+are always automatically included in all compilation units by the build
+system and should not be included manually.
+
+Don't re-invent common macros
+-----------------------------
+
+The header file `src/commonlib/bsd/include/commonlib/bsd/helpers.h`
+contains a number of macros that you should use, rather than explicitly
+coding some variant of them yourself. For example, if you need to
+calculate the length of an array, take advantage of the macro
 
 ```c
 #define ARRAY_SIZE(x) (sizeof(x) / sizeof((x)[0]))
 ```
 
-There are also min() and max() macros that do strict type checking if
-you need them. Feel free to peruse that header file to see what else is
-already defined that you shouldn't reproduce in your code.
-
 Editor modelines and other cruft
 --------------------------------
 

Documentation/getting_started/kconfig.md

@@ -607,7 +607,7 @@ int <expr> \[if <expr>\]
 
 
 ##### Example:
-    config PRE_GRAPHICS_DELAY
+    config PRE_GRAPHICS_DELAY_MS
         int "Graphics initialization delay in ms"
         default 0
         help

Documentation/ifdtool/layout.md

@@ -19,7 +19,7 @@ way to categorize anything required by the SoC but not provided by coreboot.
 | IFD Region | IFD Region name  | FMAP Name | Notes                                     |
 | index      |                  |           |                                           |
 +============+==================+===========+===========================================+
-| 0          | Flash Descriptor | SI_DESC   | Always the top 4KB of flash               |
+| 0          | Flash Descriptor | SI_DESC   | Always the top 4 KiB of flash             |
 +------------+------------------+-----------+-------------------------------------------+
 | 1          | BIOS             | SI_BIOS   | This is the region that contains coreboot |
 +------------+------------------+-----------+-------------------------------------------+
@@ -40,9 +40,9 @@ way to categorize anything required by the SoC but not provided by coreboot.
 The ifdtool can be used to manipulate a firmware image with a IFD. This tool
 will not take into account the FMAP while modifying the image which can lead to
 unexpected and hard to debug issues with the firmware image. For example if the
-ME region is defined at 6 MB in the IFD but the FMAP only allocates 4 MB for the
-ME, then when the ME is added by the ifdtool 6 MB will be written which could
-overwrite 2 MB of the BIOS.
+ME region is defined at 6 MiB in the IFD but the FMAP only allocates 4 MiB for
+the ME, then when the ME is added by the ifdtool 6 MiB will be written which
+could overwrite 2 MiB of the BIOS.
 
 In order to validate that the FMAP and the IFD are compatible the ifdtool
 provides --validate (-t) option. `ifdtool -t` will read both the IFD and the
@@ -75,4 +75,4 @@ Region mismatch between pd and SI_PDR
  FMAP area SI_PDR:
   offset: 0x007fc000
   length: 0x00004000
-```
+```

Documentation/index.md

@@ -162,7 +162,7 @@ Contents:
 
 * [Getting Started](getting_started/index.md)
 * [Tutorial](tutorial/index.md)
-* [Coding Style](coding_style.md)
+* [Coding Style](contributing/coding_style.md)
 * [Project Ideas](contributing/project_ideas.md)
 * [Documentation Ideas](contributing/documentation_ideas.md)
 * [Code of Conduct](community/code_of_conduct.md)

Documentation/mainboard/facebook/monolith.md

@@ -41,8 +41,8 @@ These can be extracted from the original flash image as follows:
 00003000:006FFFFF me
 00001000:00002fff gbe
 ```
-3) Use `ifdtool -n <layout_file> <flash_image>` to resize the *bios* region from the default 6MB
-   to 9 MB, this is required to create sufficient space for LinuxBoot.
+3) Use `ifdtool -n <layout_file> <flash_image>` to resize the *bios* region from the default 6 MiB
+   to 9 MiB, this is required to create sufficient space for LinuxBoot.
    NOTE: Please make sure only the firmware descriptor (*fd*) region is changed. Older versions
    	 of the ifdtool corrupt the *me* region.
 4) Use `ifdtool -x <resized_flash_image>` to extract the components.