px4-firmware/src/firmware/qurt/px4muorb.idl

//=======================================================================
// Copyright (c) 2016, Mark Charlebois. All rights reserved.
//
// Redistribution and use in source and binary forms, with or without
// modification, are permitted provided that the following conditions are
// met:
//     * Redistributions of source code must retain the above copyright
//       notice, this list of conditions and the following disclaimer.
//     * 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.
//     * Neither the name of The Linux Foundation 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 "AS IS" AND ANY EXPRESS OR IMPLIED
// WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
// MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT
// 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.
//=========================================================================

#include "AEEStdDef.idl"

interface px4muorb{

   /**
    * interface method to start the uorb service and initialize the muorb
    */
   AEEResult orb_initialize();

   /**
    * Interface to set an offset to hrt_absolute_time on the DSP.
    *
    * @param time_diff_us: time difference of the DSP clock to Linux clock.
    *   A positive number means the Linux clock is ahead of the DSP one.
    */
   AEEResult set_absolute_time_offset( in long time_diff_us );

   /**
    * Interface to request hrt_absolute_time on the DSP.
    * @param time_us: pointer to time in us
    */
   AEEResult get_absolute_time(rout unsigned long long time_us);

   /**
    * Interface to add a subscriber to the identified topic
    * @param topic_name
    * @return status
    *   0 == success
    *   all others is a failure.
    */
   AEEResult  add_subscriber( in string topic_name );

   /**
    * Interface to remove a subscriber for the identified topic.
    * @param topic_name
    * @return status
    *   0 == success
    *   all others is a failure.
    */
   AEEResult  remove_subscriber( in string topic_name );

   /**
    * Interface called from krait for topic data.
    * @param topic_name
    * @param data
    *   a sequence of bytes for the passed data stream.
    *   as per the HExagon Documention, the max size of this stream is 255 bytes.
    * @return status
    *   0 == success
    *   all others is a failure.
    */
   AEEResult  send_topic_data( in string topic_name, in sequence<octet> data );

   /**
    * Inteface to check if there are subscribers on the remote adsp client
    * This inteface is required as the krait app can be restarted without adsp
    * being re-started.  In this scenario the krait app does not know if there
    * is subscriber on the remote end(ie adsp).
    * @param topic_name
    *   The name of the topic for which the subscription needs to be checked.
    * @param rout int status
    *   The status of the subscription, 0=no-subscribers, 1 = more than one subscriber.
    * @return status
    *   0 == success
    *   all others is a failure.
    */
   AEEResult is_subscriber_present( in string topic_name, rout long status );

   /**
    * Interface to receive data from adsp.  Since there is only one interface, the different message
    * types are identified by the msg_type field.
    * @param msg_type
    *   The possible values are:
    *   1 ==> add_subscriber
    *   2 ==> remove_subscriber
    *   3 ==> recieve_topic_data
    * @note: for message types, 1 & 2, the data pointer returned is null with length of 0.
    * @param topic_name
    *   The topic being returned.
    * @param data
    *   the data stream
    * @param bytes_returned
    *   The number of bytes returned in the byte buffer.
    * @return status
    *   0 == success
    *   all others is a failure.
    */
   AEEResult  receive_msg( rout long msg_type, rout string topic_name, rout sequence<octet> data, rout long bytes_returned );

   /**
    * Since the receive_msg is a blocking call, the client will not be able to peform a clean shutdown.  Calling this
    * function will unblock the receive msg an return an error code.
    * Ideally this should be implemented as a time for the receive msg call.
    * @param none
    * @return status
    *    0 = success
    *    all others is a failure.
    **/
    AEEResult unblock_recieve_msg();

    /**
     * This interface will perform a bulk read from the adsp and return the data buffer.
     * The structure of the messages is as follows
     * +----------------+-----------+---------------+----------+----------------+
     * | Topic Name Len | datal_len |TopicName(nullterminated) |   data bytes   |
     * +----------------+-----------+---------------+----------+----------------+
     * |<-- 2 bytes  -->|<-2bytes-> |<-- topicnamelen bytes -->|<-datalenbytes->|
     * +----------------+---------------------------+----------+----------------+
     * @param data
     *    The output buffer where the data needs to be copied
     * @param bytes_returned
     *    The number of bytes the buffer is filled up by.
     * @param topic_count
     *    The numbe of topics filled in the buffer.
     * @return status
     *    0 = success
     *    all others is a failure.
     **/
    AEEResult receive_bulk_data( rout sequence<octet> data, rout long bytes_returned, rout long topic_count );
};