1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
|
/* Copyright (c) 2016, NVIDIA CORPORATION. All rights reserved.
* NVIDIA CORPORATION and its licensors retain all intellectual property
* and proprietary rights in and to this software, related documentation
* and any modifications thereto. Any use, reproduction, disclosure or
* distribution of this software and related documentation without an express
* license agreement from NVIDIA CORPORATION is strictly prohibited. */
#ifndef NV_RESULT_H
#define NV_RESULT_H
#include <assert.h>
/** \addtogroup core
@{
*/
/*! Result is designed to be compatible with COM HRESULT.
It's layout in bits is as follows
Severity | Facility | Code
---------|----------|-----
31 | 30-16 | 15-0
Severity - 1 fail, 0 is success.
Facility is where the error originated from
Code is the code specific to the facility.
The layout is designed such that failure is a negative number, and success is positive due to Result
being represented by an Int32.
Result codes have the following style
1. NV_name
2. NV_s_f_name
3. NV_s_name
where s is severity as a single letter S - success, and E for error
Style 1 is reserved for NV_OK and NV_FAIL as they are so common and not tied to a facility
s is S for success, E for error
f is the short version of the facility name
For the common used NV_OK and NV_FAIL, the name prefix is dropped
It is acceptable to expand 'f' to a longer name to differentiate a name
ie for a facility 'DRIVER' it might make sense to have an error of the form NV_E_DRIVER_OUT_OF_MEMORY */
typedef int NvResult;
//! Make a result
#define NV_MAKE_RESULT(sev, fac, code) ((((int)(sev))<<31) | (((int)(fac))<<16) | ((int)(code)))
//! Will be 0 - for ok, 1 for failure
#define NV_GET_RESULT_SEVERITY(r) ((int)(((NvUInt32)(r)) >> 31))
//! Will be 0 - for ok, 1 for failure
#define NV_GET_RESULT_FACILITY(r) ((int)(((r) >> 16) & 0x7fff))
//! Get the result code
#define NV_GET_RESULT_CODE(r) ((int)((r) & 0xffff))
#define NV_SEVERITY_ERROR 1
#define NV_SEVERITY_SUCCESS 0
#define NV_MAKE_ERROR(fac, code) NV_MAKE_RESULT(NV_SEVERITY_ERROR, NV_FACILITY_##fac, code)
#define NV_MAKE_SUCCESS(fac, code) NV_MAKE_RESULT(NV_SEVERITY_SUCCESS, NV_FACILITY_##fac, code)
/*************************** Facilities ************************************/
//! General - careful to make compatible with HRESULT
#define NV_FACILITY_GENERAL 0
//! Base facility -> so as to not clash with HRESULT values
#define NV_FACILITY_BASE 0x100
/*! Facilities numbers must be unique across a project to make the resulting result a unique number!
It can be useful to have a consistent short name for a facility, as used in the name prefix */
#define NV_FACILITY_DISK (NV_FACILITY_BASE + 1)
#define NV_FACILITY_INTERFACE (NV_FACILITY_BASE + 2)
#define NV_FACILITY_UNKNOWN (NV_FACILITY_BASE + 3)
#define NV_FACILITY_MEMORY (NV_FACILITY_BASE + 4)
#define NV_FACILITY_MISC (NV_FACILITY_BASE + 5)
/// Base for external facilities. Facilities should be unique across modules.
#define NV_FACILITY_EXTERNAL_BASE 0x200
#define NV_FACILITY_HAIR (NV_FACILITY_EXTERNAL_BASE + 1)
/* *************************** Codes **************************************/
// Memory
#define NV_E_MEM_OUT_OF_MEMORY NV_MAKE_ERROR(MEMORY, 1)
#define NV_E_MEM_BUFFER_TOO_SMALL NV_MAKE_ERROR(MEMORY, 2)
//! NV_OK indicates success, and is equivalent to NV_MAKE_RESULT(0, NV_FACILITY_GENERAL, 0)
#define NV_OK 0
//! NV_FAIL is the generic failure code - meaning a serious error occurred and the call couldn't complete
#define NV_FAIL NV_MAKE_ERROR(GENERAL, 1)
//! Used to identify a Result that has yet to be initialized.
//! It defaults to failure such that if used incorrectly will fail, as similar in concept to using an uninitialized variable.
#define NV_E_MISC_UNINITIALIZED NV_MAKE_ERROR(MISC, 2)
//! Returned from an async method meaning the output is invalid (thus an error), but a result for the request is pending, and will be returned on a subsequent call with the async handle.
#define NV_E_MISC_PENDING NV_MAKE_ERROR(MISC, 3)
//! Indicates that a handle passed in as parameter to a method is invalid.
#define NV_E_MISC_INVALID_HANDLE NV_MAKE_ERROR(MISC, 4)
/*! Set NV_HANDLE_RESULT_FAIL(x) to code to be executed whenever an error occurs, and is detected by one of the macros */
#ifndef NV_HANDLE_RESULT_FAIL
# define NV_HANDLE_RESULT_FAIL(x)
#endif
/* !!!!!!!!!!!!!!!!!!!!!!!!! Checking codes !!!!!!!!!!!!!!!!!!!!!!!!!!!!!! */
//! Use to test if a result was failure. Never use result != NV_OK to test for failure, as there may be successful codes != NV_OK.
#define NV_FAILED(status) ((status) < 0)
//! Use to test if a result succeeded. Never use result == NV_OK to test for success, as will detect other successful codes as a failure.
#define NV_SUCCEEDED(status) ((status) >= 0)
//! Helper macro, that makes it easy to add result checking to calls in functions/methods that themselves return Result.
#define NV_RETURN_ON_FAIL(x) { NvResult _res = (x); if (NV_FAILED(_res)) { NV_HANDLE_RESULT_FAIL(_res); return _res; } }
//! Helper macro that can be used to test the return value from a call, and will return in a void method/function
#define NV_RETURN_VOID_ON_FAIL(x) { NvResult _res = (x); if (NV_FAILED(_res)) { NV_HANDLE_RESULT_FAIL(_res); return; } }
//! Helper macro that will return false on failure.
#define NV_RETURN_FALSE_ON_FAIL(x) { NvResult _res = (x); if (NV_FAILED(_res)) { NV_HANDLE_RESULT_FAIL(_res); return false; } }
//! Helper macro that will assert if the return code from a call is failure, also returns the failure.
#define NV_CORE_ASSERT_ON_FAIL(x) { NvResult _res = (x); if (NV_FAILED(_res)) { assert(false); return _res; } }
//! Helper macro that will assert if the result from a call is a failure, also returns.
#define NV_CORE_ASSERT_VOID_ON_FAIL(x) { NvResult _res = (x); if (NV_FAILED(_res)) { assert(false); return; } }
#if __cplusplus
namespace nvidia {
typedef NvResult Result;
} // namespace nvidia
#endif
/** @} */
#endif
|