sched/event: add nxevent_getmask api

In certain cases, when the event-wait thread is awakened,
  it needs to know the specific mask bit that triggered it,
  so that it can branch to different paths accordingly.
  This patch introduces the nxevent_getmask function to address this requirement.

Signed-off-by: Chengdong Wang <wangchengdong@lixiang.com>

Documentation/reference/os/events.rst

@@ -139,6 +139,14 @@ Notifier Chain Interfaces
   :param delay: Ticks to wait from the start time until the event is posted,
                 If ticks is zero, then this function is equivalent to nxevent_trywait().
 
+.. c:function:: nxevent_mask_t nxevent_getmask(FAR nxevent_t *event)
+
+  This function returns the event mask value of the current event object.
+
+  :param event: Location to return the event group reference.
+
+  :return: The event mask value of the current event object.
+
 .. c:function:: int nxevent_open(FAR nxevent_t **event, FAR const char *name, int oflags, ...)
 
   This function establishes a connection between named event groups and a

include/nuttx/event.h

@@ -332,6 +332,27 @@ nxevent_mask_t nxevent_trywait(FAR nxevent_t *event, nxevent_mask_t events,
 
 nxevent_mask_t nxevent_clear(FAR nxevent_t *event, nxevent_mask_t mask);
 
+/****************************************************************************
+ * Name: nxevent_getmask
+ *
+ * Description:
+ *   Get the event mask of the given event object.
+ *
+ * Input Parameters:
+ *   event - Address of the event object
+ *
+ * Returned Value:
+ *   Returns the event mask value of the event object.
+ *
+  * Notes:
+ *   - This is an internal OS interface and must not be invoked directly
+ *     by user applications.
+ *   - This function is safe to call from an interrupt handler.
+ *
+ ****************************************************************************/
+
+nxevent_mask_t nxevent_getmask(FAR nxevent_t *event);
+
 /****************************************************************************
  * Name: nxevent_open
  *

sched/event/CMakeLists.txt

@@ -31,7 +31,8 @@ if(CONFIG_SCHED_EVENTS)
     event_reset.c
     event_destroy.c
     event_wait.c
-    event_clear.c)
+    event_clear.c
+    event_getmask.c)
 endif()
 
 target_sources(sched PRIVATE ${CSRCS})

sched/event/Make.defs

@@ -23,7 +23,7 @@
 # Add event-related files to the build
 
 ifeq ($(CONFIG_SCHED_EVENTS),y)
-  CSRCS += event_init.c event_post.c event_reset.c event_destroy.c event_wait.c event_clear.c
+  CSRCS += event_init.c event_post.c event_reset.c event_destroy.c event_wait.c event_clear.c event_getmask.c
 endif
 
 # Include event build support

sched/event/event_getmask.c

@@ -0,0 +1,68 @@
+/****************************************************************************
+ * sched/event/event_getmask.c
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.  The
+ * ASF licenses this file to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance with the
+ * License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  See the
+ * License for the specific language governing permissions and limitations
+ * under the License.
+ *
+ ****************************************************************************/
+
+/****************************************************************************
+ * Included Files
+ ****************************************************************************/
+
+#include <nuttx/sched.h>
+
+#include "event.h"
+
+/****************************************************************************
+ * Public Functions
+ ****************************************************************************/
+
+/****************************************************************************
+ * Name: nxevent_getmask
+ *
+ * Description:
+ *   Get the event mask of the given event object.
+ *
+ * Input Parameters:
+ *   event - Address of the event object
+ *
+ * Returned Value:
+ *   Returns the event mask value of the event object.
+ *
+ * Notes:
+ *   - This is an internal OS interface and must not be invoked directly
+ *     by user applications.
+ *   - This function is safe to call from an interrupt handler.
+ *
+ ****************************************************************************/
+
+nxevent_mask_t nxevent_getmask(FAR nxevent_t *event)
+{
+  nxevent_mask_t events;
+  irqstate_t flags;
+
+  DEBUGASSERT(event != NULL);
+
+  flags = spin_lock_irqsave(&event->lock);
+
+  events = event->events;
+
+  spin_unlock_irqrestore(&event->lock, flags);
+
+  return events;
+}