From nobody Mon Mar 20 20:13:24 2023 X-Original-To: dev-commits-src-all@mlmmj.nyi.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mlmmj.nyi.freebsd.org (Postfix) with ESMTP id 4PgQsc4nKHz40Bqw; Mon, 20 Mar 2023 20:13:24 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from mxrelay.nyi.freebsd.org (mxrelay.nyi.freebsd.org [IPv6:2610:1c1:1:606c::19:3]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256 client-signature RSA-PSS (4096 bits) client-digest SHA256) (Client CN "mxrelay.nyi.freebsd.org", Issuer "R3" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 4PgQsc462Kz3HjM; Mon, 20 Mar 2023 20:13:24 +0000 (UTC) (envelope-from git@FreeBSD.org) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1679343204; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=gj7DVzVIqfpjq9xn8ndix3S6SK+ToQ0Q64f9tRHGEEI=; b=nZt9ggfrqcxlcGoU5ZoqfAGvAg0CUmADidX/9jjXepKIeK6znJh230AQUfW1ukn4w5bb73 dqR+bw2FDtTbbj+MKe9dug92qcUU5ytu+fIW6zPH9R1F9YVkd0KzyX2zIJCHZ2x6S8xVfT TVU76e61WeeSSvASiQRrmap57Rkbl2Hf+mNH4g63Tf7cKDyEuH0q7s7c+rp4bpp3puS7vO Is2ViDQp9M+PUVK1ltOM/Y5IQQ3Tv3OD9HZCwmZHbB9KL60vDT9IMJwT1h86b+vlrpZt0G lGrvS4UNRgs9mJ1Ve8Zd6z4cFA6D2H6JWObDWhKqC7UQTRpcsT54d/lhIlRK1w== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1679343204; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=gj7DVzVIqfpjq9xn8ndix3S6SK+ToQ0Q64f9tRHGEEI=; b=aKGBY8gOKdz/qxDYgH9IWVyeOrFPc7UJjUSFIC9bRIghkU7nScaV7+yojck2HD0Y7Ss88h BTI8wh9DcPuumF/iJx2Hr5D3gkgAn+IMt9elPaL1111x5tCY2n3dJD3OXLrSb48jgC9xgv rAgDOvzzMz3gyLEhf+b+hXfepDvBibyL/1xX7GQlAhOclDHl4K4iGs8wHHFNSXtGRFKi8B CDZYIaQLj7sDJB4MwsqRIhbjZzB+oEwor3gEzgiO8nV+/ETwMjF7fJlNdoui7B5pDmN6lb S8tooNtKfblajOh5SsC9gn5TZYmq8SnKqx50GrgGnxgiSf8DJGUOKU1KJf6dOw== ARC-Authentication-Results: i=1; mx1.freebsd.org; none ARC-Seal: i=1; s=dkim; d=freebsd.org; t=1679343204; a=rsa-sha256; cv=none; b=rGEmOtTRbnMDuZDCiO/X1XW60J6pM+zr2ZHc4pzaN4J+qLUpYDjDMefXVQD8s//WOvUy5S de6lIpu1DzuisjyZo6lR1l7Gmid4eurNR2ZTJJdiRn+eQYqiaVkKDG0N2VKpOtOLHDvY11 cWFfF9r9ZYotx41H47M0ug6fSMVKXIoh1q9wTEY8a2TO7jArfzvnHRdjh4LOL5Ewc3ngwO H3pJoycCczAxyal5xkFAINjsT7i6S/dDBMBYlsBTKUDGzjiZlhRCLNBF2lVYjb9MJWhdDi iFDyjnElU3PbetraMmOgt1//W4DvWTOPDIbTPFdn43KYMMfRTjSi3dsU2dgPjg== Received: from gitrepo.freebsd.org (gitrepo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:5]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256) (Client did not present a certificate) by mxrelay.nyi.freebsd.org (Postfix) with ESMTPS id 4PgQsc39ydzkSj; Mon, 20 Mar 2023 20:13:24 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from gitrepo.freebsd.org ([127.0.1.44]) by gitrepo.freebsd.org (8.16.1/8.16.1) with ESMTP id 32KKDOFf033070; Mon, 20 Mar 2023 20:13:24 GMT (envelope-from git@gitrepo.freebsd.org) Received: (from git@localhost) by gitrepo.freebsd.org (8.16.1/8.16.1/Submit) id 32KKDOLE033069; Mon, 20 Mar 2023 20:13:24 GMT (envelope-from git) Date: Mon, 20 Mar 2023 20:13:24 GMT Message-Id: <202303202013.32KKDOLE033069@gitrepo.freebsd.org> To: src-committers@FreeBSD.org, dev-commits-src-all@FreeBSD.org, dev-commits-src-main@FreeBSD.org From: Mitchell Horne Subject: git: 43db15b16aa6 - main - critical(9): small updates List-Id: Commit messages for all branches of the src repository List-Archive: https://lists.freebsd.org/archives/dev-commits-src-all List-Help: List-Post: List-Subscribe: List-Unsubscribe: Sender: owner-dev-commits-src-all@freebsd.org X-BeenThere: dev-commits-src-all@freebsd.org MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Git-Committer: mhorne X-Git-Repository: src X-Git-Refname: refs/heads/main X-Git-Reftype: branch X-Git-Commit: 43db15b16aa6ee24613d0b25cbf50f2aef5850d1 Auto-Submitted: auto-generated X-ThisMailContainsUnwantedMimeParts: N The branch main has been updated by mhorne: URL: https://cgit.FreeBSD.org/src/commit/?id=43db15b16aa6ee24613d0b25cbf50f2aef5850d1 commit 43db15b16aa6ee24613d0b25cbf50f2aef5850d1 Author: Mitchell Horne AuthorDate: 2023-03-20 19:50:50 +0000 Commit: Mitchell Horne CommitDate: 2023-03-20 20:12:11 +0000 critical(9): small updates - Document CRITICAL_ASSERT() in this man page. - Clarify that a thread may also handle interrupts in a critical section, not only faults/exceptions. - Note the negative effects of critical section abuse - Some other minor clarifications - Add short SEE ALSO Reviewed by: kib, markj, rpokala, Pau Amma MFC after: 1 week Sponsored by: The FreeBSD Foundation Differential Revision: https://reviews.freebsd.org/D39130 --- share/man/man9/Makefile | 3 ++- share/man/man9/critical_enter.9 | 48 +++++++++++++++++++++++++++++++++-------- 2 files changed, 41 insertions(+), 10 deletions(-) diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile index 2d8d0e94c71b..fdd81ba18b11 100644 --- a/share/man/man9/Makefile +++ b/share/man/man9/Makefile @@ -929,7 +929,8 @@ MLINKS+=cpuset.9 CPUSET_T_INITIALIZER.9 \ cpuset.9 CPU_OR_ATOMIC.9 \ cpuset.9 CPU_COPY_STORE_REL.9 MLINKS+=critical_enter.9 critical.9 \ - critical_enter.9 critical_exit.9 + critical_enter.9 critical_exit.9 \ + critical_enter.9 CRITICAL_ASSERT.9 MLINKS+=crypto_buffer.9 crypto_apply.9 \ crypto_buffer.9 crypto_apply_buf.9 \ crypto_buffer.9 crypto_buffer_contiguous_segment.9 \ diff --git a/share/man/man9/critical_enter.9 b/share/man/man9/critical_enter.9 index 3da3ac1d96a1..8a702e3c44fd 100644 --- a/share/man/man9/critical_enter.9 +++ b/share/man/man9/critical_enter.9 @@ -23,7 +23,7 @@ .\" .\" $FreeBSD$ .\" -.Dd October 5, 2005 +.Dd March 20, 2023 .Dt CRITICAL_ENTER 9 .Os .Sh NAME @@ -37,15 +37,24 @@ .Fn critical_enter "void" .Ft void .Fn critical_exit "void" +.Fn CRITICAL_ASSERT "struct thread *td" .Sh DESCRIPTION These functions are used to prevent preemption in a critical region of code. All that is guaranteed is that the thread currently executing on a CPU will not be preempted. -Specifically, a thread in a critical region will not migrate to another -CPU while it is in a critical region. +Specifically, a thread in a critical region will not migrate to another CPU +while it is in a critical region, nor will the current CPU switch to a +different thread. The current CPU may still trigger faults and exceptions during a critical section; however, these faults are usually fatal. .Pp +The CPU might also receive and handle interrupts within a critical section. +When this occurs the interrupt exit will not result in a context switch, and +execution will continue in the critical section. +Thus, the net effect of a critical section on the current thread's execution is +similar to running with interrupts disabled, except that timer interrupts and +filtered interrupt handlers do not incur a latency penalty. +.Pp The .Fn critical_enter and @@ -56,18 +65,39 @@ while the current thread is in a critical section, then the preemption will be deferred until the current thread exits the outermost critical section. .Pp -Note that these functions are not required to provide any inter-CPU -synchronization, data protection, or memory ordering guarantees and thus -should +Note that these functions do not provide any inter-CPU synchronization, data +protection, or memory ordering guarantees, and thus should .Em not be used to protect shared data structures. .Pp -These functions should be used with care as an infinite loop within a -critical region will deadlock the CPU. +These functions should be used with care as an unbound or infinite loop within +a critical region will deadlock the CPU. Also, they should not be interlocked with operations on mutexes, sx locks, -semaphores, or other synchronization primitives. +semaphores, or other synchronization primitives, as these primitives may +require a context switch to operate. One exception to this is that spin mutexes include a critical section, so in certain cases critical sections may be interlocked with spin mutexes. +.Pp +Critical regions should be only as wide as necessary. +That is, code which does not require the critical section to operate correctly +should be excluded from its bounds whenever possible. +Abuse of critical sections has an effect on overall system latency and timer +precision, since disabling preemption will delay the execution of threaded +interrupt handlers and +.Xr callout 9 +events on the current CPU. +.Pp +The +.Fn CRITICAL_ASSERT +macro verifies that the provided thread +.Fa td +is currently executing in a critical section. +It is a wrapper around +.Xr KASSERT 9 . +.Sh SEE ALSO +.Xr callout 9 , +.Xr KASSERT 9 , +.Xr locking 9 .Sh HISTORY These functions were introduced in .Fx 5.0 .