Skip to content
Snippets Groups Projects
Commit c5984295 authored by Beat Küng's avatar Beat Küng Committed by tumbili
Browse files

uORB doc: remove redundant doc & update existing one (describe the _multi methods)

parent e9019582
No related branches found
No related tags found
No related merge requests found
Hide whitespace changes
Inline Side-by-side
src/modules/uORB/uORB.cpp
+ 0
− 226
View file @ c5984295
......@@ -40,86 +40,17 @@
#include "uORBManager.hpp"
#include "uORBCommon.hpp"
/**
* Advertise as the publisher of a topic.
*
* This performs the initial advertisement of a topic; it creates the topic
* node in /obj if required and publishes the initial data.
*
* Any number of advertisers may publish to a topic; publications are atomic
* but co-ordination between publishers is not provided by the ORB.
*
* @param meta The uORB metadata (usually from the ORB_ID() macro)
* for the topic.
* @param data A pointer to the initial data to be published.
* For topics updated by interrupt handlers, the advertisement
* must be performed from non-interrupt context.
* @return ERROR on error, otherwise returns a handle
* that can be used to publish to the topic.
* If the topic in question is not known (due to an
* ORB_DEFINE with no corresponding ORB_DECLARE)
* this function will return -1 and set errno to ENOENT.
*/
orb_advert_t orb_advertise(const struct orb_metadata *meta, const void *data)
{
return uORB::Manager::get_instance()->orb_advertise(meta, data);
}
/**
* Advertise as the publisher of a topic.
*
* This performs the initial advertisement of a topic; it creates the topic
* node in /obj if required and publishes the initial data.
*
* Any number of advertisers may publish to a topic; publications are atomic
* but co-ordination between publishers is not provided by the ORB.
*
* @param meta The uORB metadata (usually from the ORB_ID() macro)
* for the topic.
* @param data A pointer to the initial data to be published.
* For topics updated by interrupt handlers, the advertisement
* must be performed from non-interrupt context.
* @param instance Pointer to an integer which will yield the instance ID (0-based)
* of the publication.
* @param priority The priority of the instance. If a subscriber subscribes multiple
* instances, the priority allows the subscriber to prioritize the best
* data source as long as its available.
* @return ERROR on error, otherwise returns a handle
* that can be used to publish to the topic.
* If the topic in question is not known (due to an
* ORB_DEFINE with no corresponding ORB_DECLARE)
* this function will return -1 and set errno to ENOENT.
*/
orb_advert_t orb_advertise_multi(const struct orb_metadata *meta, const void *data, int *instance,
int priority)
{
return uORB::Manager::get_instance()->orb_advertise_multi(meta, data, instance, priority);
}
/**
* Advertise as the publisher of a topic.
*
* This performs the initial advertisement of a topic; it creates the topic
* node in /obj if required and publishes the initial data.
*
* Any number of advertisers may publish to a topic; publications are atomic
* but co-ordination between publishers is not provided by the ORB.
*
* @param meta The uORB metadata (usually from the ORB_ID() macro)
* for the topic.
* @param data A pointer to the initial data to be published.
* For topics updated by interrupt handlers, the advertisement
* must be performed from non-interrupt context.
* @param instance Pointer to an integer which will yield the instance ID (0-based)
* of the publication.
* @param priority The priority of the instance. If a subscriber subscribes multiple
* instances, the priority allows the subscriber to prioritize the best
* data source as long as its available.
* @return ERROR on error, zero on success.
* If the topic in question is not known (due to an
* ORB_DEFINE with no corresponding ORB_DECLARE)
* this function will return -1 and set errno to ENOENT.
*/
int orb_publish_auto(const struct orb_metadata *meta, orb_advert_t *handle, const void *data, int *instance,
int priority)
{
......@@ -137,175 +68,46 @@ int orb_publish_auto(const struct orb_metadata *meta, orb_advert_t *handle, cons
return -1;
}
/**
* Publish new data to a topic.
*
* The data is atomically published to the topic and any waiting subscribers
* will be notified. Subscribers that are not waiting can check the topic
* for updates using orb_check and/or orb_stat.
*
* @param meta The uORB metadata (usually from the ORB_ID() macro)
* for the topic.
* @handle The handle returned from orb_advertise.
* @param data A pointer to the data to be published.
* @return OK on success, ERROR otherwise with errno set accordingly.
*/
int orb_publish(const struct orb_metadata *meta, orb_advert_t handle, const void *data)
{
return uORB::Manager::get_instance()->orb_publish(meta, handle, data);
}
/**
* Subscribe to a topic.
*
* The returned value is a file descriptor that can be passed to poll()
* in order to wait for updates to a topic, as well as topic_read,
* orb_check and orb_stat.
*
* Subscription will succeed even if the topic has not been advertised;
* in this case the topic will have a timestamp of zero, it will never
* signal a poll() event, checking will always return false and it cannot
* be copied. When the topic is subsequently advertised, poll, check,
* stat and copy calls will react to the initial publication that is
* performed as part of the advertisement.
*
* Subscription will fail if the topic is not known to the system, i.e.
* there is nothing in the system that has declared the topic and thus it
* can never be published.
*
* @param meta The uORB metadata (usually from the ORB_ID() macro)
* for the topic.
* @return ERROR on error, otherwise returns a handle
* that can be used to read and update the topic.
* If the topic in question is not known (due to an
* ORB_DEFINE_OPTIONAL with no corresponding ORB_DECLARE)
* this function will return -1 and set errno to ENOENT.
*/
int orb_subscribe(const struct orb_metadata *meta)
{
return uORB::Manager::get_instance()->orb_subscribe(meta);
}
/**
* Subscribe to a multi-instance of a topic.
*
* The returned value is a file descriptor that can be passed to poll()
* in order to wait for updates to a topic, as well as topic_read,
* orb_check and orb_stat.
*
* Subscription will succeed even if the topic has not been advertised;
* in this case the topic will have a timestamp of zero, it will never
* signal a poll() event, checking will always return false and it cannot
* be copied. When the topic is subsequently advertised, poll, check,
* stat and copy calls will react to the initial publication that is
* performed as part of the advertisement.
*
* Subscription will fail if the topic is not known to the system, i.e.
* there is nothing in the system that has declared the topic and thus it
* can never be published.
*
* @param meta The uORB metadata (usually from the ORB_ID() macro)
* for the topic.
* @param instance The instance of the topic. Instance 0 matches the
* topic of the orb_subscribe() call, higher indices
* are for topics created with orb_publish_multi().
* @return ERROR on error, otherwise returns a handle
* that can be used to read and update the topic.
* If the topic in question is not known (due to an
* ORB_DEFINE_OPTIONAL with no corresponding ORB_DECLARE)
* this function will return -1 and set errno to ENOENT.
*/
int orb_subscribe_multi(const struct orb_metadata *meta, unsigned instance)
{
return uORB::Manager::get_instance()->orb_subscribe_multi(meta, instance);
}
/**
* Unsubscribe from a topic.
*
* @param handle A handle returned from orb_subscribe.
* @return OK on success, ERROR otherwise with errno set accordingly.
*/
int orb_unsubscribe(int handle)
{
return uORB::Manager::get_instance()->orb_unsubscribe(handle);
}
/**
* Fetch data from a topic.
*
* This is the only operation that will reset the internal marker that
* indicates that a topic has been updated for a subscriber. Once poll
* or check return indicating that an updaet is available, this call
* must be used to update the subscription.
*
* @param meta The uORB metadata (usually from the ORB_ID() macro)
* for the topic.
* @param handle A handle returned from orb_subscribe.
* @param buffer Pointer to the buffer receiving the data, or NULL
* if the caller wants to clear the updated flag without
* using the data.
* @return OK on success, ERROR otherwise with errno set accordingly.
*/
int orb_copy(const struct orb_metadata *meta, int handle, void *buffer)
{
return uORB::Manager::get_instance()->orb_copy(meta, handle, buffer);
}
/**
* Check whether a topic has been published to since the last orb_copy.
*
* This check can be used to determine whether to copy the topic when
* not using poll(), or to avoid the overhead of calling poll() when the
* topic is likely to have updated.
*
* Updates are tracked on a per-handle basis; this call will continue to
* return true until orb_copy is called using the same handle. This interface
* should be preferred over calling orb_stat due to the race window between
* stat and copy that can lead to missed updates.
*
* @param handle A handle returned from orb_subscribe.
* @param updated Set to true if the topic has been updated since the
* last time it was copied using this handle.
* @return OK if the check was successful, ERROR otherwise with
* errno set accordingly.
*/
int orb_check(int handle, bool *updated)
{
return uORB::Manager::get_instance()->orb_check(handle, updated);
}
/**
* Return the last time that the topic was updated.
*
* @param handle A handle returned from orb_subscribe.
* @param time Returns the absolute time that the topic was updated, or zero if it has
* never been updated. Time is measured in microseconds.
* @return OK on success, ERROR otherwise with errno set accordingly.
*/
int orb_stat(int handle, uint64_t *time)
{
return uORB::Manager::get_instance()->orb_stat(handle, time);
}
/**
* Check if a topic has already been created.
*
* @param meta ORB topic metadata.
* @param instance ORB instance
* @return OK if the topic exists, ERROR otherwise with errno set accordingly.
*/
int orb_exists(const struct orb_metadata *meta, int instance)
{
return uORB::Manager::get_instance()->orb_exists(meta, instance);
}
/**
* Get the number of published instances of a topic group
*
* @param meta ORB topic metadata.
* @return The number of published instances of this topic
*/
int orb_group_count(const struct orb_metadata *meta)
{
unsigned instance = 0;
......@@ -317,39 +119,11 @@ int orb_group_count(const struct orb_metadata *meta)
return instance;
}
/**
* Return the priority of the topic
*
* @param handle A handle returned from orb_subscribe.
* @param priority Returns the priority of this topic. This is only relevant for
* topics which are published by multiple publishers (e.g. mag0, mag1, etc.)
* and allows a subscriber to automatically pick the topic with the highest
* priority, independent of the startup order of the associated publishers.
* @return OK on success, ERROR otherwise with errno set accordingly.
*/
int orb_priority(int handle, int32_t *priority)
{
return uORB::Manager::get_instance()->orb_priority(handle, priority);
}
/**
* Set the minimum interval between which updates are seen for a subscription.
*
* If this interval is set, the subscriber will not see more than one update
* within the period.
*
* Specifically, the first time an update is reported to the subscriber a timer
* is started. The update will continue to be reported via poll and orb_check, but
* once fetched via orb_copy another update will not be reported until the timer
* expires.
*
* This feature can be used to pace a subscriber that is watching a topic that
* would otherwise update too quickly.
*
* @param handle A handle returned from orb_subscribe.
* @param interval An interval period in milliseconds.
* @return OK on success, ERROR otherwise with ERRNO set accordingly.
*/
int orb_set_interval(int handle, unsigned interval)
{
return uORB::Manager::get_instance()->orb_set_interval(handle, interval);
......
src/modules/uORB/uORB.h
+ 14
− 188
View file @ c5984295
......@@ -132,216 +132,64 @@ __BEGIN_DECLS
typedef void *orb_advert_t;
/**
* Advertise as the publisher of a topic.
*
* This performs the initial advertisement of a topic; it creates the topic
* node in /obj if required and publishes the initial data.
*
* Any number of advertisers may publish to a topic; publications are atomic
* but co-ordination between publishers is not provided by the ORB.
*
* @param meta The uORB metadata (usually from the ORB_ID() macro)
* for the topic.
* @param data A pointer to the initial data to be published.
* For topics updated by interrupt handlers, the advertisement
* must be performed from non-interrupt context.
* @return ERROR on error, otherwise returns a handle
* that can be used to publish to the topic.
* If the topic in question is not known (due to an
* ORB_DEFINE with no corresponding ORB_DECLARE)
* this function will return -1 and set errno to ENOENT.
* @see uORB::Manager::orb_advertise()
*/
extern orb_advert_t orb_advertise(const struct orb_metadata *meta, const void *data) __EXPORT;
/**
* Advertise as the publisher of a topic.
*
* This performs the initial advertisement of a topic; it creates the topic
* node in /obj if required and publishes the initial data.
*
* Any number of advertisers may publish to a topic; publications are atomic
* but co-ordination between publishers is not provided by the ORB.
*
* @param meta The uORB metadata (usually from the ORB_ID() macro)
* for the topic.
* @param data A pointer to the initial data to be published.
* For topics updated by interrupt handlers, the advertisement
* must be performed from non-interrupt context.
* @param instance Pointer to an integer which will yield the instance ID (0-based,
* limited by ORB_MULTI_MAX_INSTANCES) of the publication.
* @param priority The priority of the instance. If a subscriber subscribes multiple
* instances, the priority allows the subscriber to prioritize the best
* data source as long as its available.
* @return ERROR on error, otherwise returns a handle
* that can be used to publish to the topic.
* If the topic in question is not known (due to an
* ORB_DEFINE with no corresponding ORB_DECLARE)
* this function will return -1 and set errno to ENOENT.
* @see uORB::Manager::orb_advertise_multi()
*/
extern orb_advert_t orb_advertise_multi(const struct orb_metadata *meta, const void *data, int *instance,
int priority) __EXPORT;
/**
* Advertise and publish as the publisher of a topic.
* Advertise as the publisher of a topic.
*
* This performs the initial advertisement of a topic; it creates the topic
* node in /obj if required and publishes the initial data.
*
* Any number of advertisers may publish to a topic; publications are atomic
* but co-ordination between publishers is not provided by the ORB.
*
* @param meta The uORB metadata (usually from the ORB_ID() macro)
* for the topic.
* @param data A pointer to the initial data to be published.
* For topics updated by interrupt handlers, the advertisement
* must be performed from non-interrupt context.
* @param instance Pointer to an integer which will yield the instance ID (0-based,
* limited by ORB_MULTI_MAX_INSTANCES) of the publication.
* @param priority The priority of the instance. If a subscriber subscribes multiple
* instances, the priority allows the subscriber to prioritize the best
* data source as long as its available.
* @return zero on success, error number on failure
* @see uORB::Manager::orb_advertise_multi() for meaning of the individual parameters
*/
extern int orb_publish_auto(const struct orb_metadata *meta, orb_advert_t *handle, const void *data, int *instance,
int priority);
/**
* Publish new data to a topic.
*
* The data is atomically published to the topic and any waiting subscribers
* will be notified. Subscribers that are not waiting can check the topic
* for updates using orb_check and/or orb_stat.
*
* @param meta The uORB metadata (usually from the ORB_ID() macro)
* for the topic.
* @handle The handle returned from orb_advertise.
* @param data A pointer to the data to be published.
* @return OK on success, ERROR otherwise with errno set accordingly.
* @see uORB::Manager::orb_publish()
*/
extern int orb_publish(const struct orb_metadata *meta, orb_advert_t handle, const void *data) __EXPORT;
/**
* Subscribe to a topic.
*
* The returned value is a file descriptor that can be passed to poll()
* in order to wait for updates to a topic, as well as topic_read,
* orb_check and orb_stat.
*
* Subscription will succeed even if the topic has not been advertised;
* in this case the topic will have a timestamp of zero, it will never
* signal a poll() event, checking will always return false and it cannot
* be copied. When the topic is subsequently advertised, poll, check,
* stat and copy calls will react to the initial publication that is
* performed as part of the advertisement.
*
* Subscription will fail if the topic is not known to the system, i.e.
* there is nothing in the system that has declared the topic and thus it
* can never be published.
*
* @param meta The uORB metadata (usually from the ORB_ID() macro)
* for the topic.
* @return ERROR on error, otherwise returns a handle
* that can be used to read and update the topic.
* If the topic in question is not known (due to an
* ORB_DEFINE_OPTIONAL with no corresponding ORB_DECLARE)
* this function will return -1 and set errno to ENOENT.
* @see uORB::Manager::orb_subscribe()
*/
extern int orb_subscribe(const struct orb_metadata *meta) __EXPORT;
/**
* Subscribe to a multi-instance of a topic.
*
* The returned value is a file descriptor that can be passed to poll()
* in order to wait for updates to a topic, as well as topic_read,
* orb_check and orb_stat.
*
* Subscription will succeed even if the topic has not been advertised;
* in this case the topic will have a timestamp of zero, it will never
* signal a poll() event, checking will always return false and it cannot
* be copied. When the topic is subsequently advertised, poll, check,
* stat and copy calls will react to the initial publication that is
* performed as part of the advertisement.
*
* Subscription will fail if the topic is not known to the system, i.e.
* there is nothing in the system that has declared the topic and thus it
* can never be published.
*
* @param meta The uORB metadata (usually from the ORB_ID() macro)
* for the topic.
* @param instance The instance of the topic. Instance 0 matches the
* topic of the orb_subscribe() call, higher indices
* are for topics created with orb_publish_multi().
* Instance is limited by ORB_MULTI_MAX_INSTANCES.
* @return ERROR on error, otherwise returns a handle
* that can be used to read and update the topic.
* If the topic in question is not known (due to an
* ORB_DEFINE_OPTIONAL with no corresponding ORB_DECLARE)
* this function will return -1 and set errno to ENOENT.
* @see uORB::Manager::orb_subscribe_multi()
*/
extern int orb_subscribe_multi(const struct orb_metadata *meta, unsigned instance) __EXPORT;
/**
* Unsubscribe from a topic.
*
* @param handle A handle returned from orb_subscribe.
* @return OK on success, ERROR otherwise with errno set accordingly.
* @see uORB::Manager::orb_unsubscribe()
*/
extern int orb_unsubscribe(int handle) __EXPORT;
/**
* Fetch data from a topic.
*
* This is the only operation that will reset the internal marker that
* indicates that a topic has been updated for a subscriber. Once poll
* or check return indicating that an updaet is available, this call
* must be used to update the subscription.
*
* @param meta The uORB metadata (usually from the ORB_ID() macro)
* for the topic.
* @param handle A handle returned from orb_subscribe.
* @param buffer Pointer to the buffer receiving the data, or NULL
* if the caller wants to clear the updated flag without
* using the data.
* @return OK on success, ERROR otherwise with errno set accordingly.
* @see uORB::Manager::orb_copy()
*/
extern int orb_copy(const struct orb_metadata *meta, int handle, void *buffer) __EXPORT;
/**
* Check whether a topic has been published to since the last orb_copy.
*
* This check can be used to determine whether to copy the topic when
* not using poll(), or to avoid the overhead of calling poll() when the
* topic is likely to have updated.
*
* Updates are tracked on a per-handle basis; this call will continue to
* return true until orb_copy is called using the same handle. This interface
* should be preferred over calling orb_stat due to the race window between
* stat and copy that can lead to missed updates.
*
* @param handle A handle returned from orb_subscribe.
* @param updated Set to true if the topic has been updated since the
* last time it was copied using this handle.
* @return OK if the check was successful, ERROR otherwise with
* errno set accordingly.
* @see uORB::Manager::orb_advertise()
*/
extern int orb_check(int handle, bool *updated) __EXPORT;
/**
* Return the last time that the topic was updated.
*
* @param handle A handle returned from orb_subscribe.
* @param time Returns the absolute time that the topic was updated, or zero if it has
* never been updated. Time is measured in microseconds.
* @return OK on success, ERROR otherwise with errno set accordingly.
* @see uORB::Manager::orb_stat()
*/
extern int orb_stat(int handle, uint64_t *time) __EXPORT;
/**
* Check if a topic has already been created.
*
* @param meta ORB topic metadata.
* @param instance ORB instance
* @return OK if the topic exists, ERROR otherwise with errno set accordingly.
* @see uORB::Manager::orb_exists()
*/
extern int orb_exists(const struct orb_metadata *meta, int instance) __EXPORT;
......@@ -354,34 +202,12 @@ extern int orb_exists(const struct orb_metadata *meta, int instance) __EXPORT;
extern int orb_group_count(const struct orb_metadata *meta) __EXPORT;
/**
* Return the priority of the topic
*
* @param handle A handle returned from orb_subscribe.
* @param priority Returns the priority of this topic. This is only relevant for
* topics which are published by multiple publishers (e.g. mag0, mag1, etc.)
* and allows a subscriber to automatically pick the topic with the highest
* priority, independent of the startup order of the associated publishers.
* @return OK on success, ERROR otherwise with errno set accordingly.
* @see uORB::Manager::orb_priority()
*/
extern int orb_priority(int handle, int32_t *priority) __EXPORT;
/**
* Set the minimum interval between which updates are seen for a subscription.
*
* If this interval is set, the subscriber will not see more than one update
* within the period.
*
* Specifically, the first time an update is reported to the subscriber a timer
* is started. The update will continue to be reported via poll and orb_check, but
* once fetched via orb_copy another update will not be reported until the timer
* expires.
*
* This feature can be used to pace a subscriber that is watching a topic that
* would otherwise update too quickly.
*
* @param handle A handle returned from orb_subscribe.
* @param interval An interval period in milliseconds.
* @return OK on success, ERROR otherwise with ERRNO set accordingly.
* @see uORB::Manager::orb_set_interval()
*/
extern int orb_set_interval(int handle, unsigned interval) __EXPORT;
......
src/modules/uORB/uORBManager.hpp
+ 21
− 5
View file @ c5984295
......@@ -78,6 +78,9 @@ public:
* Any number of advertisers may publish to a topic; publications are atomic
* but co-ordination between publishers is not provided by the ORB.
*
* Internally this will call orb_advertise_multi with an instance of 0 and
* default priority.
*
* @param meta The uORB metadata (usually from the ORB_ID() macro)
* for the topic.
* @param data A pointer to the initial data to be published.
......@@ -100,16 +103,23 @@ public:
* Any number of advertisers may publish to a topic; publications are atomic
* but co-ordination between publishers is not provided by the ORB.
*
* The multi can be used to create multiple independent instances of the same topic
* (each instance has its own buffer).
* This is useful for multiple publishers who publish the same topic. The subscriber
* then subscribes to all instances and chooses which source he wants to use.
*
* @param meta The uORB metadata (usually from the ORB_ID() macro)
* for the topic.
* @param data A pointer to the initial data to be published.
* For topics updated by interrupt handlers, the advertisement
* must be performed from non-interrupt context.
* @param instance Pointer to an integer which will yield the instance ID (0-based)
* of the publication.
* of the publication. This is an output parameter and will be set to the newly
* created instance, ie. 0 for the first advertiser, 1 for the next and so on.
* @param priority The priority of the instance. If a subscriber subscribes multiple
* instances, the priority allows the subscriber to prioritize the best
* data source as long as its available.
* data source as long as its available. The subscriber is responsible to check
* and handle different priorities (@see orb_priority()).
* @return ERROR on error, otherwise returns a handle
* that can be used to publish to the topic.
* If the topic in question is not known (due to an
......@@ -153,6 +163,8 @@ public:
* there is nothing in the system that has declared the topic and thus it
* can never be published.
*
* Internally this will call orb_subscribe_multi with instance 0.
*
* @param meta The uORB metadata (usually from the ORB_ID() macro)
* for the topic.
* @return ERROR on error, otherwise returns a handle
......@@ -181,11 +193,15 @@ public:
* there is nothing in the system that has declared the topic and thus it
* can never be published.
*
* If a publisher publishes multiple instances the subscriber should
* subscribe to each instance with orb_subscribe_multi
* (@see orb_advertise_multi()).
*
* @param meta The uORB metadata (usually from the ORB_ID() macro)
* for the topic.
* @param instance The instance of the topic. Instance 0 matches the
* topic of the orb_subscribe() call, higher indices
* are for topics created with orb_publish_multi().
* are for topics created with orb_advertise_multi().
* @return ERROR on error, otherwise returns a handle
* that can be used to read and update the topic.
* If the topic in question is not known (due to an
......@@ -265,8 +281,8 @@ public:
* @param handle A handle returned from orb_subscribe.
* @param priority Returns the priority of this topic. This is only relevant for
* topics which are published by multiple publishers (e.g. mag0, mag1, etc.)
* and allows a subscriber to automatically pick the topic with the highest
* priority, independent of the startup order of the associated publishers.
* and allows a subscriber to pick the topic with the highest priority,
* independent of the startup order of the associated publishers.
* @return OK on success, ERROR otherwise with errno set accordingly.
*/
int orb_priority(int handle, int32_t *priority) ;
......
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment