• R/O
  • SSH
  • HTTPS

chibios: Commit


Commit MetaInfo

Revision13203 (tree)
Time2019-11-28 23:09:41
Authorgdisirio

Log Message

(empty log message)

Change Summary

Incremental Difference

--- trunk/os/oslib/include/chjobs.h (nonexistent)
+++ trunk/os/oslib/include/chjobs.h (revision 13203)
@@ -0,0 +1,354 @@
1+/*
2+ ChibiOS - Copyright (C) 2006..2018 Giovanni Di Sirio.
3+
4+ This file is part of ChibiOS.
5+
6+ ChibiOS is free software; you can redistribute it and/or modify
7+ it under the terms of the GNU General Public License as published by
8+ the Free Software Foundation; either version 3 of the License, or
9+ (at your option) any later version.
10+
11+ ChibiOS is distributed in the hope that it will be useful,
12+ but WITHOUT ANY WARRANTY; without even the implied warranty of
13+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14+ GNU General Public License for more details.
15+
16+ You should have received a copy of the GNU General Public License
17+ along with this program. If not, see <http://www.gnu.org/licenses/>.
18+*/
19+
20+/**
21+ * @file chjobs.h
22+ * @brief Jobs Queues structures and macros.
23+ * @details This module implements queues of generic jobs to be delegated
24+ * asynchronously to a pool of dedicated threads.
25+ * Operations defined for Jobs Queues
26+ * - <b>Get</b>: An job object is taken from the pool of the
27+ * available jobs.
28+ * - <b>Post</b>: A job is posted to the queue, it will be
29+ * returned to the pool after execution.
30+ * .
31+ *
32+ * @addtogroup oslib_jobs_queues
33+ * @{
34+ */
35+
36+#ifndef CHJOBS_H
37+#define CHJOBS_H
38+
39+#if (CH_CFG_USE_JOBS == TRUE) || defined(__DOXYGEN__)
40+
41+/*===========================================================================*/
42+/* Module constants. */
43+/*===========================================================================*/
44+
45+/*===========================================================================*/
46+/* Module pre-compile time settings. */
47+/*===========================================================================*/
48+
49+/*===========================================================================*/
50+/* Derived constants and error checks. */
51+/*===========================================================================*/
52+
53+#if CH_CFG_USE_MEMPOOLS == FALSE
54+#error "CH_CFG_USE_JOBS requires CH_CFG_USE_MEMPOOLS"
55+#endif
56+
57+#if CH_CFG_USE_SEMAPHORES == FALSE
58+#error "CH_CFG_USE_JOBS requires CH_CFG_USE_SEMAPHORES"
59+#endif
60+
61+#if CH_CFG_USE_MAILBOXES == FALSE
62+#error "CH_CFG_USE_JOBS requires CH_CFG_USE_MAILBOXES"
63+#endif
64+
65+/*===========================================================================*/
66+/* Module data structures and types. */
67+/*===========================================================================*/
68+
69+/**
70+ * @brief Type of a jobs queue.
71+ */
72+typedef struct ch_jobs_queue {
73+ /**
74+ * @brief Pool of the free jobs.
75+ */
76+ guarded_memory_pool_t free;
77+ /**
78+ * @brief Mailbox of the sent jobs.
79+ */
80+ mailbox_t mbx;
81+} jobs_queue_t;
82+
83+/**
84+ * @brief Type of a job function.
85+ */
86+typedef void (*job_function_t)(void *arg);
87+
88+/**
89+ * @brief Type of a job descriptor.
90+ */
91+typedef struct ch_job_descriptor {
92+ /**
93+ * @brief Job function.
94+ */
95+ job_function_t jobfunc;
96+ /**
97+ * @brief Argument to be passed to the job function.
98+ */
99+ void *jobarg;
100+} job_descriptor_t;
101+
102+/*===========================================================================*/
103+/* Module macros. */
104+/*===========================================================================*/
105+
106+/*===========================================================================*/
107+/* External declarations. */
108+/*===========================================================================*/
109+
110+#ifdef __cplusplus
111+extern "C" {
112+#endif
113+
114+#ifdef __cplusplus
115+}
116+#endif
117+
118+/*===========================================================================*/
119+/* Module inline functions. */
120+/*===========================================================================*/
121+
122+/**
123+ * @brief Initializes a jobs queue object.
124+ *
125+ * @param[out] jqp pointer to a @p jobs_queue_t structure
126+ * @param[in] jobsn number of jobs available
127+ * @param[in] jobsbuf pointer to the buffer of jobs, it must be able
128+ * to hold @p jobsn @p job_descriptor_t structures
129+ * @param[in] msgbuf pointer to the buffer of messages, it must be able
130+ * to hold @p jobsn @p msg_t messages
131+ *
132+ * @init
133+ */
134+static inline void chJobsObjectInit(jobs_queue_t *jqp,
135+ size_t jobsn,
136+ job_descriptor_t *jobsbuf,
137+ msg_t *msgbuf) {
138+
139+ chDbgCheck((jobsn > 0U) && (jobsbuf != NULL) && (msgbuf != NULL));
140+
141+ chGuardedPoolObjectInit(&jqp->free, sizeof (job_descriptor_t));
142+ chGuardedPoolLoadArray(&jqp->free, (void *)jobsbuf, jobsn);
143+ chMBObjectInit(&jqp->mbx, msgbuf, jobsn);
144+}
145+
146+/**
147+ * @brief Allocates a free job object.
148+ *
149+ * @param[in] jqp pointer to a @p jobs_queue_t structure
150+ * @return The pointer to the allocated job object.
151+ * @retval NULL if a job object is not immediately available.
152+ *
153+ * @iclass
154+ */
155+static inline job_descriptor_t *chGetTakeI(jobs_queue_t *jqp) {
156+
157+ return chGuardedPoolAllocI(&jqp->free);
158+}
159+
160+/**
161+ * @brief Allocates a free job object.
162+ *
163+ * @param[in] jqp pointer to a @p jobs_queue_t structure
164+ * @param[in] timeout the number of ticks before the operation timeouts,
165+ * the following special values are allowed:
166+ * - @a TIME_IMMEDIATE immediate timeout.
167+ * - @a TIME_INFINITE no timeout.
168+ * .
169+ * @return The pointer to the allocated job object.
170+ * @retval NULL if a job object is not available within the specified
171+ * timeout.
172+ *
173+ * @sclass
174+ */
175+static inline job_descriptor_t *chJobsGetTimeoutS(jobs_queue_t *jqp,
176+ sysinterval_t timeout) {
177+
178+ return chGuardedPoolAllocTimeoutS(&jqp->free, timeout);
179+}
180+
181+/**
182+ * @brief Allocates a free job object.
183+ *
184+ * @param[in] jqp pointer to a @p jobs_queue_t structure
185+ * @param[in] timeout the number of ticks before the operation timeouts,
186+ * the following special values are allowed:
187+ * - @a TIME_IMMEDIATE immediate timeout.
188+ * - @a TIME_INFINITE no timeout.
189+ * .
190+ * @return The pointer to the allocated job object.
191+ * @retval NULL if a job object is not available within the specified
192+ * timeout.
193+ *
194+ * @api
195+ */
196+static inline job_descriptor_t *chJobsGetTimeout(jobs_queue_t *jqp,
197+ sysinterval_t timeout) {
198+
199+ return chGuardedPoolAllocTimeout(&jqp->free, timeout);
200+}
201+
202+/**
203+ * @brief Posts a job object.
204+ * @note By design the object can be always immediately posted.
205+ *
206+ * @param[in] jqp pointer to a @p jobs_queue_t structure
207+ * @param[in] jp pointer to the job object to be posted
208+ *
209+ * @iclass
210+ */
211+static inline void chJobsPostI(jobs_queue_t *jqp, job_descriptor_t *jp) {
212+ msg_t msg;
213+
214+ msg = chMBPostI(&jqp->mbx, (msg_t)jp);
215+ chDbgAssert(msg == MSG_OK, "post failed");
216+}
217+
218+/**
219+ * @brief Posts a job object.
220+ * @note By design the object can be always immediately posted.
221+ *
222+ * @param[in] jqp pointer to a @p jobs_queue_t structure
223+ * @param[in] jp pointer to the job object to be posted
224+ *
225+ * @sclass
226+ */
227+static inline void chJobsPostS(jobs_queue_t *jqp, job_descriptor_t *jp) {
228+ msg_t msg;
229+
230+ msg = chMBPostTimeoutS(&jqp->mbx, (msg_t)jp, TIME_IMMEDIATE);
231+ chDbgAssert(msg == MSG_OK, "post failed");
232+}
233+
234+/**
235+ * @brief Posts a job object.
236+ * @note By design the object can be always immediately posted.
237+ *
238+ * @param[in] jqp pointer to a @p jobs_queue_t structure
239+ * @param[in] jp pointer to the job object to be posted
240+ *
241+ * @api
242+ */
243+static inline void chJobsPost(jobs_queue_t *jqp, job_descriptor_t *jp) {
244+ msg_t msg;
245+
246+ msg = chMBPostTimeout(&jqp->mbx, (msg_t)jp, TIME_IMMEDIATE);
247+ chDbgAssert(msg == MSG_OK, "post failed");
248+}
249+
250+/**
251+ * @brief Posts an high priority job object.
252+ * @note By design the object can be always immediately posted.
253+ *
254+ * @param[in] jqp pointer to a @p jobs_queue_t structure
255+ * @param[in] jp pointer to the job object to be posted
256+ *
257+ * @iclass
258+ */
259+static inline void chJobsPostAheadI(jobs_queue_t *jqp, job_descriptor_t *jp) {
260+ msg_t msg;
261+
262+ msg = chMBPostAheadI(&jqp->mbx, (msg_t)jp);
263+ chDbgAssert(msg == MSG_OK, "post failed");
264+}
265+
266+/**
267+ * @brief Posts an high priority job object.
268+ * @note By design the object can be always immediately posted.
269+ *
270+ * @param[in] jqp pointer to a @p jobs_queue_t structure
271+ * @param[in] jp pointer to the job object to be posted
272+ *
273+ * @sclass
274+ */
275+static inline void chJobsPostAheadS(jobs_queue_t *jqp, job_descriptor_t *jp) {
276+ msg_t msg;
277+
278+ msg = chMBPostAheadTimeoutS(&jqp->mbx, (msg_t)jp, TIME_IMMEDIATE);
279+ chDbgAssert(msg == MSG_OK, "post failed");
280+}
281+
282+/**
283+ * @brief Posts an high priority job object.
284+ * @note By design the object can be always immediately posted.
285+ *
286+ * @param[in] jqp pointer to a @p jobs_queue_t structure
287+ * @param[in] jp pointer to the job object to be posted
288+ *
289+ * @api
290+ */
291+static inline void chJobsPostAhead(jobs_queue_t *jqp, job_descriptor_t *jp) {
292+ msg_t msg;
293+
294+ msg = chMBPostAheadTimeout(&jqp->mbx, (msg_t)jp, TIME_IMMEDIATE);
295+ chDbgAssert(msg == MSG_OK, "post failed");
296+}
297+
298+/**
299+ * @brief Waits for a job then executes it.
300+ *
301+ * @param[in] jqp pointer to a @p jobs_queue_t structure
302+ * @return The function outcome.
303+ * @retval MSG_OK if a job has been executed.
304+ * @retval MSG_RESET if the internal mailbox has been reset.
305+ */
306+static inline msg_t chJobsDispatch(jobs_queue_t *jqp) {
307+ msg_t msg, jmsg;
308+
309+ msg = chMBFetchTimeout(&jqp->mbx, &jmsg, TIME_INFINITE);
310+ if (msg == MSG_OK) {
311+ job_descriptor_t *jp = (job_descriptor_t *)jmsg;
312+
313+ /* Invoking the job function.*/
314+ jp->jobfunc(jp->jobarg);
315+
316+ /* Returning the job descriptor object.*/
317+ chGuardedPoolFree(&jqp->free, (void *)jp);
318+ }
319+
320+ return msg;
321+}
322+
323+/**
324+ * @brief Waits for a job then executes it.
325+ *
326+ * @param[in] jqp pointer to a @p jobs_queue_t structure
327+ * @return The function outcome.
328+ * @retval MSG_OK if a job has been executed.
329+ * @retval MSG_TIMEOUT if a timeout occurred.
330+ * @retval MSG_RESET if the internal mailbox has been reset.
331+ */
332+static inline msg_t chJobsDispatchTimeout(jobs_queue_t *jqp,
333+ sysinterval_t timeout) {
334+ msg_t msg, jmsg;
335+
336+ msg = chMBFetchTimeout(&jqp->mbx, &jmsg, timeout);
337+ if (msg == MSG_OK) {
338+ job_descriptor_t *jp = (job_descriptor_t *)jmsg;
339+
340+ /* Invoking the job function.*/
341+ jp->jobfunc(jp->jobarg);
342+
343+ /* Returning the job descriptor object.*/
344+ chGuardedPoolFree(&jqp->free, (void *)jp);
345+ }
346+
347+ return msg;
348+}
349+
350+#endif /* CH_CFG_USE_JOBS == TRUE */
351+
352+#endif /* CHJOBS_H */
353+
354+/** @} */
--- trunk/os/oslib/include/chlib.h (revision 13202)
+++ trunk/os/oslib/include/chlib.h (revision 13203)
@@ -113,10 +113,14 @@
113113 #endif
114114
115115 #if !defined(CH_CFG_USE_DELEGATES)
116-//#error "CH_CFG_USE_DELEGATES not defined in chconf.h"
117-#define CH_CFG_USE_DELEGATES 0
116+#error "CH_CFG_USE_DELEGATES not defined in chconf.h"
118117 #endif
119118
119+#if !defined(CH_CFG_USE_JOBS)
120+//#error "CH_CFG_USE_JOBS not defined in chconf.h"
121+#define CH_CFG_USE_JOBS 1
122+#endif
123+
120124 /* Objects factory options checks.*/
121125 #if !defined(CH_CFG_USE_FACTORY)
122126 #error "CH_CFG_USE_FACTORY not defined in chconf.h"
@@ -180,7 +184,6 @@
180184 (CH_LICENSE_FEATURES == CH_FEATURES_BASIC)
181185
182186 /* Restricted subsystems.*/
183-#undef CH_CFG_USE_MEMCORE
184187 #undef CH_CFG_USE_HEAP
185188 #undef CH_CFG_USE_MEMPOOLS
186189 #undef CH_CFG_USE_OBJ_FIFOS
@@ -187,14 +190,14 @@
187190 #undef CH_CFG_USE_PIPES
188191 #undef CH_CFG_USE_OBJ_CACHES
189192 #undef CH_CFG_USE_DELEGATES
193+#undef CH_CFG_USE_JOBS
190194
191-#define CH_CFG_USE_MEMCORE FALSE
192195 #define CH_CFG_USE_HEAP FALSE
193196 #define CH_CFG_USE_MEMPOOLS FALSE
194197 #define CH_CFG_USE_OBJ_FIFOS FALSE
195198 #define CH_CFG_USE_PIPES FALSE
196199 #define CH_CFG_USE_OBJ_CACHES FALSE
197-#define CH_CFG_USE_DELEGATES FALSE
200+#define CH_CFG_USE_JOBS FALSE
198201
199202 #endif /* (CH_CUSTOMER_LIC_OSLIB == FALSE) ||
200203 (CH_LICENSE_FEATURES == CH_FEATURES_BASIC) */
@@ -225,6 +228,7 @@
225228 #include "chpipes.h"
226229 #include "chobjcaches.h"
227230 #include "chdelegates.h"
231+#include "chjobs.h"
228232 #include "chfactory.h"
229233
230234 /*===========================================================================*/
--- trunk/os/oslib/include/chobjfifos.h (revision 13202)
+++ trunk/os/oslib/include/chobjfifos.h (revision 13203)
@@ -422,6 +422,7 @@
422422
423423 return chMBFetchTimeout(&ofp->mbx, (msg_t *)objpp, timeout);
424424 }
425+
425426 #endif /* CH_CFG_USE_OBJ_FIFOS == TRUE */
426427
427428 #endif /* CHOBJFIFOS_H */
--- trunk/readme.txt (revision 13202)
+++ trunk/readme.txt (revision 13203)
@@ -79,7 +79,7 @@
7979 chMsgWaitTimeoutS(), chMsgWaitTimeout().
8080 - RT: Improvements to messages, new functions chMsgWaitS(),
8181 chMsgWaitTimeoutS(), chMsgWaitTimeout(), chMsgPollS(),
82- chMsgPoll().
82+ chMsgPoll().
8383 - HAL: TRNG support added to STM32F7xx, STM32G0xx, STM32G4xx,
8484 STM32H7xx and STM32L0xx.
8585 - NEW: Added support for .cc files extensions in makefiles.
Show on old repository browser