[rtems commit] timecounter: Merge FreeBSD change r315287

[Sebastian Huber]

Module:    rtems
Branch:    master
Commit:    5167d0e76bd0e153a5147064c96e2aa5e7282bc2
Changeset: http://git.rtems.org/rtems/commit/?id=5167d0e76bd0e153a5147064c96e2aa5e7282bc2

Author:    Eric van Gyzen <vangyzen at FreeBSD.org>
Date:      Tue Mar 14 22:02:02 2017 +0000

timecounter: Merge FreeBSD change r315287

Add missing pieces of r315280

I moved this branch from github to a private server, and pulled from the
wrong one when committing r315280, so I failed to include two recent commits.
Thankfully, they were only cosmetic and were included in the review.
Specifically:

Add documentation, polish comments, and improve style(9).

Tested by:	pho (r315280)
MFC after:	2 weeks
Sponsored by:	Dell EMC
Differential Revision:	https://reviews.freebsd.org/D9791

Update #3175.

---

 cpukit/score/src/kern_tc.c | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/cpukit/score/src/kern_tc.c b/cpukit/score/src/kern_tc.c
index 81c2131..fa53fcd 100644
--- a/cpukit/score/src/kern_tc.c
+++ b/cpukit/score/src/kern_tc.c
@@ -1418,6 +1418,15 @@ static bool
 sleeping_on_old_rtc(struct thread *td)
 {
 
+	/*
+	 * td_rtcgen is modified by curthread when it is running,
+	 * and by other threads in this function.  By finding the thread
+	 * on a sleepqueue and holding the lock on the sleepqueue
+	 * chain, we guarantee that the thread is not running and that
+	 * modifying td_rtcgen is safe.  Setting td_rtcgen to zero informs
+	 * the thread that it was woken due to a real-time clock adjustment.
+	 * (The declaration of td_rtcgen refers to this comment.)
+	 */
 	if (td->td_rtcgen != 0 && td->td_rtcgen != rtc_generation) {
 		td->td_rtcgen = 0;
 		return (true);
@@ -1461,6 +1470,7 @@ _Timecounter_Set_clock(const struct bintime *_bt,
 #ifndef __rtems__
 	tc_windup(&bt);
 	mtx_unlock_spin(&tc_setclock_mtx);
+
 	/* Avoid rtc_generation == 0, since td_rtcgen == 0 is special. */
 	atomic_add_rel_int(&rtc_generation, 2);
 	sleepq_chains_remove_matching(sleeping_on_old_rtc);