vboot: add documentation for different switches in vb2_api.h

List two switches with their documentation in vb2_api.h:
- NEED_VB2_SHA_LIBRARY
- NEED_VB20_INTERNALS

BUG=b:124141368, b:124192753
TEST=Build locally
TEST=/work/vboot/src/repohooks/pre-upload.py
TEST=make clean && make runtests
TEST=make clean && COV=1 make coverage && make coverage_html
BRANCH=none

Change-Id: I91798f9211ddb09fa57cc958f6c9a662b9d41192
Signed-off-by: Joel Kitching <kitching@google.com>
Reviewed-on: https://chromium-review.googlesource.com/1480751
Commit-Ready: Joel Kitching <kitching@chromium.org>
Tested-by: Joel Kitching <kitching@chromium.org>
Reviewed-by: Simon Glass <sjg@chromium.org>
Reviewed-by: Randall Spangler <rspangler@chromium.org>
Reviewed-by: Furquan Shaikh <furquan@chromium.org>
Reviewed-by: Julius Werner <jwerner@chromium.org>

1 files changed, 15 insertions, 0 deletions

diff --git a/firmware/include/vb2_api.h b/firmware/include/vb2_api.h
index d59b6731..4ef64a88 100644
--- a/firmware/include/vb2_api.h
+++ b/firmware/include/vb2_api.h
@@ -12,6 +12,21 @@
  * without churning other projects' source code.
  */
 
+/*
+ * Switches that can be used in conjunction with this header file:
+ *
+ * #define NEED_VB2_SHA_LIBRARY
+ *   SHA library APIs may be called by external firmware as well as vboot.
+ *   This is permissible because the SHA library routines below don't interact
+ *   with the rest of vboot.
+ *
+ * #define NEED_VB20_INTERNALS
+ *   Allows the caller to peek into vboot2 data structures, by including a
+ *   specific set of extra header files listed in vb2_api.h.  Including this
+ *   switch means the caller is broken and should be fixed.  The existence of
+ *   this switch is a bug, and it should be removed when it is no longer used.
+ */
+
 #ifndef VBOOT_VB2_API_H_
 #define VBOOT_VB2_API_H_