diff options
Diffstat (limited to 'apps/uORB/uORB.h')
| -rw-r--r-- | apps/uORB/uORB.h | 264 |
1 files changed, 0 insertions, 264 deletions
diff --git a/apps/uORB/uORB.h b/apps/uORB/uORB.h deleted file mode 100644 index 82ff46ad2..000000000 --- a/apps/uORB/uORB.h +++ /dev/null @@ -1,264 +0,0 @@ -/**************************************************************************** - * - * Copyright (C) 2012 PX4 Development Team. All rights reserved. - * - * Redistribution and use in source and binary forms, with or without - * modification, are permitted provided that the following conditions - * are met: - * - * 1. Redistributions of source code must retain the above copyright - * notice, this list of conditions and the following disclaimer. - * 2. Redistributions in binary form must reproduce the above copyright - * notice, this list of conditions and the following disclaimer in - * the documentation and/or other materials provided with the - * distribution. - * 3. Neither the name PX4 nor the names of its contributors may be - * used to endorse or promote products derived from this software - * without specific prior written permission. - * - * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS - * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT - * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS - * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE - * COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, - * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, - * BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS - * OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED - * AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT - * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN - * ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE - * POSSIBILITY OF SUCH DAMAGE. - * - ****************************************************************************/ - -#ifndef _UORB_UORB_H -#define _UORB_UORB_H - -/** - * @file uORB.h - * API for the uORB lightweight object broker. - */ - -#include <sys/types.h> -#include <stdint.h> -#include <stdbool.h> - -// Hack until everything is using this header -#include <systemlib/visibility.h> - -/** - * Object metadata. - */ -struct orb_metadata { - const char *o_name; /**< unique object name */ - const size_t o_size; /**< object size */ -}; - -typedef const struct orb_metadata *orb_id_t; - -/** - * Generates a pointer to the uORB metadata structure for - * a given topic. - * - * The topic must have been declared previously in scope - * with ORB_DECLARE(). - * - * @param _name The name of the topic. - */ -#define ORB_ID(_name) &__orb_##_name - -/** - * Declare (prototype) the uORB metadata for a topic. - * - * Note that optional topics are declared weak; this allows a potential - * subscriber to attempt to subscribe to a topic that is not known to the - * system at runtime. The ORB_ID() macro will return NULL/nullptr for - * such a topic, and attempts to advertise or subscribe to it will - * return -1/ENOENT (see below). - * - * @param _name The name of the topic. - */ -#if defined(__cplusplus) -# define ORB_DECLARE(_name) extern "C" const struct orb_metadata __orb_##_name __EXPORT -# define ORB_DECLARE_OPTIONAL(_name) extern "C" const struct orb_metadata __orb_##_name __EXPORT __attribute__((weak)) -#else -# define ORB_DECLARE(_name) extern const struct orb_metadata __orb_##_name __EXPORT -# define ORB_DECLARE_OPTIONAL(_name) extern const struct orb_metadata __orb_##_name __EXPORT __attribute__((weak)) -#endif - -/** - * Define (instantiate) the uORB metadata for a topic. - * - * The uORB metadata is used to help ensure that updates and - * copies are accessing the right data. - * - * Note that there must be no more than one instance of this macro - * for each topic. - * - * @param _name The name of the topic. - * @param _struct The structure the topic provides. - */ -#define ORB_DEFINE(_name, _struct) \ - const struct orb_metadata __orb_##_name = { \ - #_name, \ - sizeof(_struct) \ - }; struct hack - -__BEGIN_DECLS - -/** - * ORB topic advertiser handle. - * - * Advertiser handles are global; once obtained they can be shared freely - * and do not need to be closed or released. - * - * This permits publication from interrupt context and other contexts where - * a file-descriptor-based handle would not otherwise be in scope for the - * publisher. - */ -typedef intptr_t 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. - */ -extern orb_advert_t orb_advertise(const struct orb_metadata *meta, const void *data) __EXPORT; - -/** - * 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. - */ -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. - */ -extern int orb_subscribe(const struct orb_metadata *meta) __EXPORT; - -/** - * Unsubscribe from a topic. - * - * @param handle A handle returned from orb_subscribe. - * @return OK on success, ERROR otherwise with errno set accordingly. - */ -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. - */ -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. - */ -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. - */ -extern int orb_stat(int handle, uint64_t *time) __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. - */ -extern int orb_set_interval(int handle, unsigned interval) __EXPORT; - -__END_DECLS - -#endif /* _UORB_UORB_H */ |