diff --git a/src/modules/uORB/uORB.cpp b/src/modules/uORB/uORB.cpp index 1578c186a9..e37a5772a7 100644 --- a/src/modules/uORB/uORB.cpp +++ b/src/modules/uORB/uORB.cpp @@ -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); diff --git a/src/modules/uORB/uORB.h b/src/modules/uORB/uORB.h index afab3cd813..5e07fc5c3e 100644 --- a/src/modules/uORB/uORB.h +++ b/src/modules/uORB/uORB.h @@ -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; diff --git a/src/modules/uORB/uORBManager.hpp b/src/modules/uORB/uORBManager.hpp index 04158234bd..094dfa96b6 100644 --- a/src/modules/uORB/uORBManager.hpp +++ b/src/modules/uORB/uORBManager.hpp @@ -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) ;