uORBMain.cpp学习

uorb_main

1. int
2. uorb_main(int argc, char *argv[])
3. {
4. if (argc < 2) {
5. usage();                                                                                            //使用说明
6. return -EINVAL;
7. }
8. /*
9. * Start/load the driver.                                                                                //开始或加载驱动
10. */
11. if (!strcmp(argv[1], "start")) {
12. if (g_dev != nullptr) {                                                                               //判断是否已经启动
13. PX4_WARN("already loaded");
14. /* user wanted to start uorb, its already running, no error */
15. return 0;
16. }
17. if (!uORB::Manager::initialize()) {                                                                     //初始化uORB::Manager
18. PX4_ERR("uorb manager alloc failed");
19. return -ENOMEM;
20. }
21. /* create the driver */                                                                                //创建一个驱动设备
22. g_dev = uORB::Manager::get_instance()->get_device_master(uORB::PUBSUB);
23. if (g_dev == nullptr) {
24. return -errno;
25. }
26. #if !defined(__PX4_QURT) && !defined(__PX4_POSIX_EAGLE) && !defined(__PX4_POSIX_EXCELSIOR)
27. /* FIXME: this fails on Snapdragon (see https://github.com/PX4/Firmware/issues/5406),
28. * so we disable logging messages to the ulog for now. This needs further investigations.
29. */
30. px4_log_initialize();
31. #endif
32. return OK;
33. }
34. /*
35. * Print driver information.                                                                            //打印设备信息status
36. */
37. if (!strcmp(argv[1], "status")) {
38. if (g_dev != nullptr) {
39. g_dev->printStatistics(true);
40. } else {
41. PX4_INFO("uorb is not running");
42. }
43. return OK;
44. }
45. //topming'li
46. if (!strcmp(argv[1], "top")) {
47. if (g_dev != nullptr) {
48. g_dev->showTop(argv + 2, argc - 2);
49. } else {
50. PX4_INFO("uorb is not running");
51. }
52. return OK;
53. }
54. usage();
55. return -EINVAL;
56. }

uORB::Manager::initialize():

1. bool uORB::Manager::initialize()
2. {
3. if (_Instance == nullptr) {
4. _Instance = new uORB::Manager();                                            //创建了一个新的uORB实例
5. }
6. return _Instance != nullptr;
7. }

uORB::Manager:

1. /**
2. * This is implemented as a singleton. This class manages creating the                                //这是一个实施的单例，这个class管理创建uORB节点给每个uORB topics
3. * uORB nodes for each uORB topics and also implements the behavor of the                             //并且也实施uORB的API行为
4. * uORB Api's.
5. */
6. class uORB::Manager : public uORBCommunicator::IChannelRxHandler
7. {
8. public:
9. // public interfaces for this class.                                                                    //公共的类接口
10. /**                                                                                                    //初始化单例，调用这个在所有事情之前
11. * Initialize the singleton. Call this before everything else.
12. * @return true on success                                                                             //返回true是成功
13. */
14. static bool initialize();
15. /**                                                                                                    //获取instance的方法
16. * Method to get the singleton instance for the uORB::Manager.
17. * Make sure initialize() is called first.                                                             //确保initialize()先被调用
18. * @return uORB::Manager*                                                                                //返回创建的uORB：：Manager*
19. */
20. static uORB::Manager *get_instance()
21. {
22. return _Instance;
23. }
24. /**
25. * Get the DeviceMaster for a given Flavor. If it does not exist,                                        //给定一个flavoe，会返回DeciveMaster* 如果不存在会创建并且初始化
26. * it will be created and initialized.
27. * Note: the first call to this is not thread-safe.                                                      //第一次调用thread-safe不是这个？
28. * @return nullptr if initialization failed (and errno will be set)                                        //初始化失败返回一个nullptr
29. */
30. uORB::DeviceMaster *get_device_master(Flavor flavor);
31. // ==== uORB interface methods ====
32. /**
33. * Advertise as the publisher of a topic.                                                                    //广告作为发布话题
34. *
35. * This performs the initial advertisement of a topic; it creates the topic                                  //执行初始化的广告topic；它创造topic
36. * node in /obj if required and publishes the initial data.
37. *
38. * Any number of advertisers may publish to a topic; publications are atomic
39. * but co-ordination between publishers is not provided by the ORB.
40. *
41. * Internally this will call orb_advertise_multi with an instance of 0 and                                    //函数内部调用了orb_advertis_multi
42. * default priority.
43. *
44. * @param meta The uORB metadata (usually from the ORB_ID() macro)                                            //uORB metadata(通常来自ORB_ID()宏）作为topic
45. * for the topic.
46. * @param data A pointer to the initial data to be published.                                                 //数据指针
47. * For topics updated by interrupt handlers, the advertisement                                                //中断处理函数
48. * must be performed from non-interrupt context.                                                              //必须执行无中断的内容
49. * @param queue_size Maximum number of buffered elements. If this is 1, no queuing is                         //最大的buffer元素个数，如果是1，没有队列被使用
50. * used.
51. * @return nullptr on error, otherwise returns an object pointer                                              //返回空指针如果错误，否则返回一个类指针
52. * that can be used to publish to the topic.                                                                  //那个可以用来公布topic
53. * If the topic in question is not known (due to an                                                           //如果topic在问题中不被知道（由于ORB_DEFINE不和ORB_DECLARE一致）
54. * ORB_DEFINE with no corresponding ORB_DECLARE)
55. * this function will return nullptr and set errno to ENOENT.                                                 //这个函数将会返回nullptr并且设置errno到ENOENT
56. */
57. orb_advert_t orb_advertise(const struct orb_metadata *meta, const void *data, unsigned int queue_size = 1)
58. {
59. return orb_advertise_multi(meta, data, nullptr, ORB_PRIO_DEFAULT, queue_size);
60. }
61. /**
62. * Advertise as the publisher of a topic.
63. *
64. * This performs the initial advertisement of a topic; it creates the topic
65. * node in /obj if required and publishes the initial data.
66. *
67. * Any number of advertisers may publish to a topic; publications are atomic
68. * but co-ordination between publishers is not provided by the ORB.
69. *
70. * The multi can be used to create multiple independent instances of the same topic                                            //用来创建多个独立接口用于相同的topic
71. * (each instance has its own buffer).                                                                                         //每个接口都有自己的buff
72. * This is useful for multiple publishers who publish the same topic. The subscriber
73. * then subscribes to all instances and chooses which source he wants to use.
74. *
75. * @param meta The uORB metadata (usually from the ORB_ID() macro)                                                            //meta通常来自于ORB_ID()宏，是uORB的metadata
76. * for the topic.
77. * @param data A pointer to the initial data to be published.                                                                //data是一个初始化要发布数据的指针
78. * For topics updated by interrupt handlers, the advertisement                                                               //通过中断处理函数更新，
79. * must be performed from non-interrupt context.
80. * @param instance Pointer to an integer which will yield the instance ID (0-based)                                          //一个整形指针，用于接口ID（0-based)
81. * of the publication. This is an output parameter and will be set to the newly                                              //创建接口等等，0是第一个广告，1是下一个，如此往下
82. * created instance, ie. 0 for the first advertiser, 1 for the next and so on.
83. * @param priority The priority of the instance. If a subscriber subscribes multiple                                         //接口的优先级
84. * instances, the priority allows the subscriber to prioritize the best
85. * data source as long as its available. The subscriber is responsible to check
86. * and handle different priorities (@see orb_priority()).
87. * @param queue_size Maximum number of buffered elements. If this is 1, no queuing is                                        //最大的buffer元素个数，如果是1，没有queuing被使用
88. * used.
89. * @return ERROR on error, otherwise returns a handle                                                                        //返回ERROR在错误时，否则返回一个句柄。用于创建一个topic和publish
90. * that can be used to publish to the topic.
91. * If the topic in question is not known (due to an
92. * ORB_DEFINE with no corresponding ORB_DECLARE)
93. * this function will return -1 and set errno to ENOENT.
94. */
95. orb_advert_t orb_advertise_multi(const struct orb_metadata *meta, const void *data, int *instance,
96. int priority, unsigned int queue_size = 1) ;
97. /**
98. * Unadvertise a topic.
99. *
100. * @param handle handle returned by orb_advertise or orb_advertise_multi.                                                                        //用于取消一个topic， handle是orb_advertise_multi返回的handle
101. * @return 0 on success
102. */
103. int orb_unadvertise(orb_advert_t handle);
104. /**
105. * Publish new data to a topic.                                                                                                                   //发布一个新的
106. *
107. * The data is atomically published to the topic and any waiting subscribers
108. * will be notified. Subscribers that are not waiting can check the topic
109. * for updates using orb_check and/or orb_stat.
110. *
111. * @param meta The uORB metadata (usually from the ORB_ID() macro)                                                                                //从ORB_ID宏的metadata
112. * for the topic.
113. * @handle The handle returned from orb_advertise.                                                                                                //orb_advertise返回的handle
114. * @param data A pointer to the data to be published.                                                                                             //publish的数据的指针
115. * @return OK on success, ERROR otherwise with errno set accordingly.                                                                             //返回OK如果成功
116. */
117. int orb_publish(const struct orb_metadata *meta, orb_advert_t handle, const void *data) ;
118. /**
119. * Subscribe to a topic.                                                                                                                          //订阅一个topic
120. *
121. * The returned value is a file descriptor that can be passed to poll()
122. * in order to wait for updates to a topic, as well as topic_read,
123. * orb_check and orb_stat.
124. *
125. * Subscription will succeed even if the topic has not been advertised;
126. * in this case the topic will have a timestamp of zero, it will never
127. * signal a poll() event, checking will always return false and it cannot
128. * be copied. When the topic is subsequently advertised, poll, check,
129. * stat and copy calls will react to the initial publication that is
130. * performed as part of the advertisement.
131. *
132. * Subscription will fail if the topic is not known to the system, i.e.
133. * there is nothing in the system that has declared the topic and thus it
134. * can never be published.
135. *
136. * Internally this will call orb_subscribe_multi with instance 0.
137. *
138. * @param meta The uORB metadata (usually from the ORB_ID() macro)                                                                                    //订阅主题的metadata
139. * for the topic.
140. * @return ERROR on error, otherwise returns a handle
141. * that can be used to read and update the topic.
142. */
143. int orb_subscribe(const struct orb_metadata *meta) ;
144. /**
145. * Subscribe to a multi-instance of a topic.                                                                                                        //订阅多个主题
146. *
147. * The returned value is a file descriptor that can be passed to poll()
148. * in order to wait for updates to a topic, as well as topic_read,
149. * orb_check and orb_stat.
150. *
151. * Subscription will succeed even if the topic has not been advertised;
152. * in this case the topic will have a timestamp of zero, it will never
153. * signal a poll() event, checking will always return false and it cannot
154. * be copied. When the topic is subsequently advertised, poll, check,
155. * stat and copy calls will react to the initial publication that is
156. * performed as part of the advertisement.
157. *
158. * Subscription will fail if the topic is not known to the system, i.e.
159. * there is nothing in the system that has declared the topic and thus it
160. * can never be published.
161. *
162. * If a publisher publishes multiple instances the subscriber should
163. * subscribe to each instance with orb_subscribe_multi
164. * (@see orb_advertise_multi()).
165. *
166. * @param meta The uORB metadata (usually from the ORB_ID() macro)
167. * for the topic.
168. * @param instance The instance of the topic. Instance 0 matches the
169. * topic of the orb_subscribe() call, higher indices
170. * are for topics created with orb_advertise_multi().
171. * @return ERROR on error, otherwise returns a handle
172. * that can be used to read and update the topic.
173. * If the topic in question is not known (due to an
174. * ORB_DEFINE_OPTIONAL with no corresponding ORB_DECLARE)
175. * this function will return -1 and set errno to ENOENT.
176. */
177. int orb_subscribe_multi(const struct orb_metadata *meta, unsigned instance) ;
178. /**
179. * Unsubscribe from a topic.
180. *
181. * @param handle A handle returned from orb_subscribe.
182. * @return OK on success, ERROR otherwise with errno set accordingly.
183. */
184. int orb_unsubscribe(int handle) ;                                                                                                //取消订阅一个主题,handle是orb_subscribe返回的句柄
185. /**
186. * Fetch data from a topic.
187. *
188. * This is the only operation that will reset the internal marker that
189. * indicates that a topic has been updated for a subscriber. Once poll
190. * or check return indicating that an updaet is available, this call
191. * must be used to update the subscription.
192. *
193. * @param meta The uORB metadata (usually from the ORB_ID() macro)
194. * for the topic.
195. * @param handle A handle returned from orb_subscribe.
196. * @param buffer Pointer to the buffer receiving the data, or NULL
197. * if the caller wants to clear the updated flag without
198. * using the data.
199. * @return OK on success, ERROR otherwise with errno set accordingly.
200. */
201. int orb_copy(const struct orb_metadata *meta, int handle, void *buffer) ;                                                        //从主题中获取数据，buffer就是接收数据存放的位置
202. /**
203. * Check whether a topic has been published to since the last orb_copy.
204. *
205. * This check can be used to determine whether to copy the topic when
206. * not using poll(), or to avoid the overhead of calling poll() when the
207. * topic is likely to have updated.
208. *
209. * Updates are tracked on a per-handle basis; this call will continue to
210. * return true until orb_copy is called using the same handle. This interface
211. * should be preferred over calling orb_stat due to the race window between
212. * stat and copy that can lead t