1/1 Better expose xenstore limits
PATCH 1/1 1/1 Better expose xenstore limits
Hi,
The attached patch announces the limits regarding:
XENSTORE_PAYLOAD_MAX, XENSTORE_ABS_PATH_MAX and XENSTORE_REL_PATH_MAX in the public xs.h.
These are already defined in xs_wire, however, not many people dig that far when using xs.h.
Since xs.h already includes xs_wire, this patch duplicates those limits as XS_PAYLOAD_MAX, XS_ABS_PATH_MAX and XS_REL_PATH_MAX. Moving these would be a pain, but they really need to be advertised.
Such limits should be obvious in the headers that people actually use outside of the kernel, saving them from wondering what went wrong.
Added comments direct people to xs_wire.h , in case those limits change.
tools/xenstore/xs.h +5 -0
@@ -23,6 +23,11 @@#include <xs_lib.h> #define XBT_NULL 0 + +/* Please see xen/io/xs_wire.h for more explantion on these limits */ +#define XS_PAYLOAD_MAX XENSTORE_PAYLOAD_MAX +#define XS_ABS_PATH_MAX XENSTORE_ABS_PATH_MAX +#define XS_REL_PATH_MAX XENSTORE_REL_PATH_MAXstruct xs_handle ;typedef uint32_t xs_transaction_t ;
_______________________________________________
Xen-devel mailing list
[email protected]
http://lists.xensource.com/xen-devel
Quoted 8 lines · Tim Post
Since
xs.halready includesxs_wire, this patch duplicates those limits asXS_PAYLOAD_MAX,XS_ABS_PATH_MAXandXS_REL_PATH_MAX. Moving these would be a pain, but they really need to be advertised.Such limits should be obvious in the headers that people actually use outside of the kernel, saving them from wondering what went wrong.
Added comments direct people to
xs_wire.h, in case those limits change.
In terms of documentation, docs/misc/xenstore.txt already does a fine job. And I think a xen/public/... header is the right place for the limits, since it is a general documented protocol-level constraint, rather than a constraint of the particular client library (which is the scope of xs.h itself).
-- Keir
Quoted 6 lines · Keir Fraser
Quoted 4 lines · Tim Post
Since
xs.halready includesxs_wire, this patch duplicates those limits asXS_PAYLOAD_MAX,XS_ABS_PATH_MAXandXS_REL_PATH_MAX. Moving these would be a pain, but they really need to be advertised.
Quoted 6 lines
Quoted 4 lines
Such limits should be obvious in the headers that people actually use outside of the kernel, saving them from wondering what went wrong.
Added comments direct people to
xs_wire.h, in case those limits change.In terms of documentation,
docs/misc/xenstore.txtalready does a fine job.
Provided such docs are actually packaged.. many install Xen (and associated DSO's and headers) via yum, apt-get, etc.
Quoted 4 lines
And I think a xen/public/... header is the right place for the limits, since it is a general documented protocol-level constraint, rather than a constraint of the particular client library (which is the scope of
xs.hitself).
Yes, it is the right place for the limits, the patch does not suggest moving them, only echoing them in the header that user space apps will include.
Someone using xs.h is going to be entirely unaware of said limits. Xenstore internals will relay an appropriate errno if the limits are exceeded, but I think many people will not know such limits exist.
Xenwire is used when developing drivers.. not user space applications.
Why not assert the limits in both at the cost of bothering the preprocessor three times?
Cheers,
--Tim
Quoted 8 lines · Tim Post
Someone using
xs.his going to be entirely unaware of said limits. Xenstore internals will relay an appropriate errno if the limits are exceeded, but I think many people will not know such limits exist.Xenwire is used when developing drivers.. not user space applications.
Why not assert the limits in both at the cost of bothering the preprocessor three times?
Defining the same thing again but with a different name just for purposes of documentation is pretty barking. I suppose it is perhaps worth a documentation comment in xs.h, but no more than that.
-- Keir
Quoted 6 lines · Keir Fraser
Quoted 4 lines · Tim Post
Someone using
xs.his going to be entirely unaware of said limits. Xenstore internals will relay an appropriate errno if the limits are exceeded, but I think many people will not know such limits exist.
Quoted 8 lines
Quoted 4 lines
Xenwire is used when developing drivers.. not user space applications.
Why not assert the limits in both at the cost of bothering the preprocessor three times?
Defining the same thing again but with a different name just for purposes of documentation is pretty barking. I suppose it is perhaps worth a documentation comment in
xs.h, but no more than that.
It is worth a mention... though it seems silly to send a patch that adds comments. However, a patch that would convert the comments in xs to doxygen format seems more useful, with the appropriate grouping, shorts, etc.
How receptive would you be to that?
Cheers,
--Tim
Quoted 10 lines · Tim Post
Quoted 3 lines
Defining the same thing again but with a different name just for purposes of documentation is pretty barking. I suppose it is perhaps worth a documentation comment in
xs.h, but no more than that.It is worth a mention... though it seems silly to send a patch that adds comments. However, a patch that would convert the comments in xs to doxygen format seems more useful, with the appropriate grouping, shorts, etc.
How receptive would you be to that?
I don't have a strong opinion. You can go wild on that if you like, assuming noone else hates doxygen format for any reason. I added a limits-related comment to xs.h by the way.
-- Keir
Quoted 11 lines · Keir Fraser
Quoted 9 lines · Tim Post
Quoted 3 lines
Defining the same thing again but with a different name just for purposes of documentation is pretty barking. I suppose it is perhaps worth a documentation comment in
xs.h, but no more than that.It is worth a mention... though it seems silly to send a patch that adds comments. However, a patch that would convert the comments in xs to doxygen format seems more useful, with the appropriate grouping, shorts, etc.
Quoted 5 lines
Quoted 1 line
How receptive would you be to that?
I don't have a strong opinion. You can go wild on that if you like, assuming noone else hates doxygen format for any reason. I added a limits-related comment to
xs.hby the way.
Well, since we have doxygen in the build, and the generated html docs are so easy to read .. seems sort of silly not to make it uniform :)
If nobody replies with a resounding PLEASE NO, I'll go ahead and do it .. libxc needs some comment love anyway.
It is very frustrating and difficult for people to write apps that work with Xen using the shipped (or wiki) documentation. All too often, what's on the wiki is not in step with unstable, so each new release is like an easter egg hunt.
I also have some autoconf macros that I'll post to help stop breakage due to structures shifting members. from the earlier days of v3 (but still in use).
Cheers,
--Tim