FIXUP: mkbp: add support for board-specific host notification

This patch improves naming and documentation for the functionality
introduced in crrev.com/c/1247000

TEST=build
BRANCH=none
BUG=b:112366846, b:112112483, b:112111610

Change-Id: Iedd2fc5492a5d35fa9c2475fe248c5aa41e83bb0
Signed-off-by: Enrico Granata <egranata@chromium.org>
Reviewed-on: https://chromium-review.googlesource.com/1258562
Reviewed-by: Aaron Durbin <adurbin@chromium.org>

2 files changed, 34 insertions, 8 deletions

diff --git a/common/mkbp_event.c b/common/mkbp_event.c
index 08e88f287e..9d643d6f46 100644
--- a/common/mkbp_event.c
+++ b/common/mkbp_event.c
@@ -34,24 +34,24 @@ static int event_is_set(uint8_t event_type)
 }
 
 #ifndef CONFIG_MKBP_USE_HOST_EVENT
-void send_mkbp_event_gpio(int active)
+void mkbp_set_host_active_via_gpio(int active)
 {
 	gpio_set_level(GPIO_EC_INT_L, !active);
 }
 #endif
 
-void send_mkbp_event_host(int active)
+void mkbp_set_host_active_via_event(int active)
 {
 	if (active)
 		host_set_single_event(EC_HOST_EVENT_MKBP);
 }
 
-__attribute__((weak)) void send_mkbp_event(int active)
+__attribute__((weak)) void mkbp_set_host_active(int active)
 {
 #ifdef CONFIG_MKBP_USE_HOST_EVENT
-	send_mkbp_event_host(active);
+	mkbp_set_host_active_via_event(active);
 #else
-	send_mkbp_event_gpio(active);
+	mkbp_set_host_active_via_gpio(active);
 #endif
 }
 
@@ -67,7 +67,7 @@ static void set_host_interrupt(int active)
 	if (old_active == 0 && active == 1)
 		mkbp_last_event_time = __hw_clock_source_read();
 
-	send_mkbp_event(active);
+	mkbp_set_host_active(active);
 
 	old_active = active;
 	interrupt_enable();
diff --git a/include/mkbp_event.h b/include/mkbp_event.h
index 3639ffb326..61eb2c9052 100644
--- a/include/mkbp_event.h
+++ b/include/mkbp_event.h
@@ -28,8 +28,34 @@ extern uint32_t mkbp_last_event_time;
  */
 int mkbp_send_event(uint8_t event_type);
 
-void send_mkbp_event_gpio(int active);
-void send_mkbp_event_host(int active);
+/*
+ * Set MKBP active event status on the AP.
+ *
+ * This communicates to the AP whether an MKBP event is currently available
+ * for processing. It is used by mkbp_send_event().
+ *
+ * The default implementation in mkbp_event.c has weak linkage and can be
+ * overridden by individual boards depending on their hardware configuration.
+ *
+ * @param active  1 if there is an event, 0 otherwise
+ */
+void mkbp_set_host_active(int active);
+
+/*
+ * Communicate an MKBP event to the host via a dedicated GPIO pin.
+ *
+ * This can be used if the board schematic has a pin reserved for this purpose.
+ */
+void mkbp_set_host_active_via_gpio(int active);
+
+/*
+ * Communicate an MKBP event to the AP via EC_HOST_EVENT.
+ *
+ * This can be used without a dedicated interrupt pin configured. It is the
+ * default behavior of mkbp_set_host_active when CONFIG_MKBP_USE_HOST_EVENT
+ * is defined in board.h.
+ */
+void mkbp_set_host_active_via_event(int active);
 
 /*
  * The struct to store the event source definition.  The get_data routine is