@@ -1638,12 +1638,12 @@ BaseType_t xQueueGiveMutexRecursive( QueueHandle_t xMutex ) PRIVILEGED_FUNCTION;
16381638 * See FreeRTOS/Source/Demo/Common/Minimal/QueueSet.c for an example using this
16391639 * function.
16401640 *
1641- * A queue set must be explicitly created using a call to xQueueCreateSet()
1642- * before it can be used. Once created, standard FreeRTOS queues and semaphores
1643- * can be added to the set using calls to xQueueAddToSet().
1644- * xQueueSelectFromSet() is then used to determine which, if any, of the queues
1645- * or semaphores contained in the set is in a state where a queue read or
1646- * semaphore take operation would be successful.
1641+ * A queue set must be explicitly created using a call to xQueueCreateSet() or
1642+ * xQueueCreateSetStatic() before it can be used. Once created, standard
1643+ * FreeRTOS queues and semaphores can be added to the set using calls to
1644+ * xQueueAddToSet(). xQueueSelectFromSet() is then used to determine which, if
1645+ * any, of the queues or semaphores contained in the set is in a state where a
1646+ * queue read or semaphore take operation would be successful.
16471647 *
16481648 * Note 1: See the documentation on https://www.freertos.org/Documentation/02-Kernel/04-API-references/07-Queue-sets/00-RTOS-queue-sets
16491649 * for reasons why queue sets are very rarely needed in practice as there are
@@ -1683,9 +1683,69 @@ BaseType_t xQueueGiveMutexRecursive( QueueHandle_t xMutex ) PRIVILEGED_FUNCTION;
16831683 QueueSetHandle_t xQueueCreateSet ( const UBaseType_t uxEventQueueLength ) PRIVILEGED_FUNCTION ;
16841684#endif
16851685
1686+ /*
1687+ * Queue sets provide a mechanism to allow a task to block (pend) on a read
1688+ * operation from multiple queues or semaphores simultaneously.
1689+ *
1690+ * See FreeRTOS/Source/Demo/Common/Minimal/QueueSet.c for an example using this
1691+ * function.
1692+ *
1693+ * A queue set must be explicitly created using a call to xQueueCreateSet()
1694+ * or xQueueCreateSetStatic() before it can be used. Once created, standard
1695+ * FreeRTOS queues and semaphores can be added to the set using calls to
1696+ * xQueueAddToSet(). xQueueSelectFromSet() is then used to determine which, if
1697+ * any, of the queues or semaphores contained in the set is in a state where a
1698+ * queue read or semaphore take operation would be successful.
1699+ *
1700+ * Note 1: See the documentation on https://www.freertos.org/Documentation/02-Kernel/04-API-references/07-Queue-sets/00-RTOS-queue-sets
1701+ * for reasons why queue sets are very rarely needed in practice as there are
1702+ * simpler methods of blocking on multiple objects.
1703+ *
1704+ * Note 2: Blocking on a queue set that contains a mutex will not cause the
1705+ * mutex holder to inherit the priority of the blocked task.
1706+ *
1707+ * Note 3: An additional 4 bytes of RAM is required for each space in a every
1708+ * queue added to a queue set. Therefore counting semaphores that have a high
1709+ * maximum count value should not be added to a queue set.
1710+ *
1711+ * Note 4: A receive (in the case of a queue) or take (in the case of a
1712+ * semaphore) operation must not be performed on a member of a queue set unless
1713+ * a call to xQueueSelectFromSet() has first returned a handle to that set member.
1714+ *
1715+ * @param uxEventQueueLength Queue sets store events that occur on
1716+ * the queues and semaphores contained in the set. uxEventQueueLength specifies
1717+ * the maximum number of events that can be queued at once. To be absolutely
1718+ * certain that events are not lost uxEventQueueLength should be set to the
1719+ * total sum of the length of the queues added to the set, where binary
1720+ * semaphores and mutexes have a length of 1, and counting semaphores have a
1721+ * length set by their maximum count value. Examples:
1722+ * + If a queue set is to hold a queue of length 5, another queue of length 12,
1723+ * and a binary semaphore, then uxEventQueueLength should be set to
1724+ * (5 + 12 + 1), or 18.
1725+ * + If a queue set is to hold three binary semaphores then uxEventQueueLength
1726+ * should be set to (1 + 1 + 1 ), or 3.
1727+ * + If a queue set is to hold a counting semaphore that has a maximum count of
1728+ * 5, and a counting semaphore that has a maximum count of 3, then
1729+ * uxEventQueueLength should be set to (5 + 3), or 8.
1730+ *
1731+ * @param pucQueueStorage pucQueueStorage must point to a uint8_t array that is
1732+ * at least large enough to hold uxEventQueueLength events.
1733+ *
1734+ * @param pxQueueBuffer Must point to a variable of type StaticQueue_t, which
1735+ * will be used to hold the queue's data structure.
1736+ *
1737+ * @return If the queue set is created successfully then a handle to the created
1738+ * queue set is returned. If pxQueueBuffer is NULL then NULL is returned.
1739+ */
1740+ #if ( ( configUSE_QUEUE_SETS == 1 ) && ( configSUPPORT_STATIC_ALLOCATION == 1 ) )
1741+ QueueSetHandle_t xQueueCreateSetStatic ( const UBaseType_t uxEventQueueLength ,
1742+ uint8_t * pucQueueStorage ,
1743+ StaticQueue_t * pxStaticQueue ) PRIVILEGED_FUNCTION ;
1744+ #endif
1745+
16861746/*
16871747 * Adds a queue or semaphore to a queue set that was previously created by a
1688- * call to xQueueCreateSet().
1748+ * call to xQueueCreateSet() or xQueueCreateSetStatic() .
16891749 *
16901750 * See FreeRTOS/Source/Demo/Common/Minimal/QueueSet.c for an example using this
16911751 * function.
0 commit comments