[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

[Xen-devel] [PATCH for-next] CODING_STYLE: Document how to handle unexpected conditions

It's not always clear what the best way is to handle unexpected
conditions: whether with ASSERT(), BUG_ON(), or some other method.
All methods have a risk of introducing security vulnerabilities and
unnecessary instabilities to production systems.

Document when to try to return an error for unexpected conditions,
when to use BUG_ON(), and when to use ASSERT().

Signed-off-by: George Dunlap <george.dunlap@xxxxxxxxxx>
CC: Ian Jackson <ian.jackson@xxxxxxxxxx>
CC: Wei Liu <wei.liu2@xxxxxxxxxx>
CC: Andrew Cooper <andrew.cooper3@xxxxxxxxxx>
CC: Jan Beulich <jbeulich@xxxxxxxx>
CC: Tim Deegan <tim@xxxxxxx>
CC: Konrad Wilk <konrad.wilk@xxxxxxxxxx>
CC: Stefano Stabellini <sstabellini@xxxxxxxxxx>
CC: Julien Grall <julien.grall@xxxxxxx>
 CODING_STYLE | 79 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 79 insertions(+)

index 6cc5b774cf..51159970c0 100644
@@ -120,3 +120,82 @@ the end of files.  It should be:
  * indent-tabs-mode: nil
  * End:
+Handling unexpected conditions
+Passing errors up the stack should be used when the caller is already
+expecting to handle errors, and the state when the error was
+discovered isn’t broken, or too hard to fix.
+BUG_ON() should be used when you can’t pass errors up the stack, and
+continuing would certainly cause a vulnerability.
+ASSERT() should be used when continuing might work, or might have an
+effect later whose badness is equal or less than that of a host crash;
+OR whose truth can be clearly observed from the code directly
+surrounding it.  In particular, using an ASSERT() along with returning
+an error code, when suitable, is a helpful pattern for finding
+violations of assumptions during testing, but minimizing impact on
+production hypervisors.
+It's frequently the case that code is writen with the assumption that
+certain conditions can never happen.  There are several possible
+actions programmers can take in these situations:
+* Programmers can simply not handle those cases in any way, other than
+perhaps to write a comment documenting what the assumption is.
+* Programmers can try to handle the case gracefully -- fixing up
+in-progress state and returning an error to the user.
+* Programmers can use ASSERT(), which will cause the check to be
+executed in DEBUG builds, and cause the hypervisor to crash if it's
+* Programmers can use BUG_ON(), which will cause the check to be
+executed in both DEBUG and non-DEBUG builds, and cause the hypervisor
+to crash if it's violated.
+In selecting which response to use, we want to achieve several goals:
+- To minimize risk of introducing security vulnerabilities,
+  particularly as the code evolves over time
+- To efficiently spend programmer time
+- To detect violations of assumptions as early as possible
+- To minimize the impact of bugs on production use cases
+The guidelines above attempt to balance these:
+- When the caller is expecting to handle errors, and there are no
+broken state at the time the unexpected condition is discovered, or
+when fixing the state is straightforward, then fixing up the state and
+returning an error is the most robust thing to do.  However, if the
+caller isn't expecting to handle errors, or if the state is difficult
+to fix, then returning an error may require extensive refactoring,
+which is not a good use of programmer time when they're certain that
+this condition cannot occur.
+- BUG_ON() will stop all hypervisor action immediately.  In situations
+where continuing might allow an attacker to escalate privilege, a
+BUG_ON() can change a privilege escalation or information leak into a
+denial-of-service (an improvement).  But in situations where
+continuing (say, returning an error) might be safe, then BUG_ON() can
+change a benign failure into denial-of-service (a degradation)
+- ASSERT() will stop the hypervisor during development, but allow
+hypervisor action to continue during production.  In situations where
+continuing will at worst result in a denial-of-service, and at best
+may have little effect other than perhaps quirky behavior, using an
+ASSERT() will allow violation of assumptions to be detected as soon as
+possible, while not causing undue degradation in production
+hypervisors.  However, in situations where continuing could cause
+privilege escalation or information leaks, using an ASSERT() can
+introduce security vulnerabilities.

Xen-devel mailing list



Lists.xenproject.org is hosted with RackSpace, monitoring our
servers 24x7x365 and backed by RackSpace's Fanatical Support®.