PX4 Firmware
PX4 Autopilot Software http://px4.io
dataman.h
Go to the documentation of this file.
1 /****************************************************************************
2  *
3  * Copyright (c) 2013, 2014 PX4 Development Team. All rights reserved.
4  *
5  * Redistribution and use in source and binary forms, with or without
6  * modification, are permitted provided that the following conditions
7  * are met:
8  *
9  * 1. Redistributions of source code must retain the above copyright
10  * notice, this list of conditions and the following disclaimer.
11  * 2. Redistributions in binary form must reproduce the above copyright
12  * notice, this list of conditions and the following disclaimer in
13  * the documentation and/or other materials provided with the
14  * distribution.
15  * 3. Neither the name PX4 nor the names of its contributors may be
16  * used to endorse or promote products derived from this software
17  * without specific prior written permission.
18  *
19  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
20  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
21  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
22  * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
23  * COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
24  * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
25  * BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS
26  * OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
27  * AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
28  * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
29  * ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
30  * POSSIBILITY OF SUCH DAMAGE.
31  *
32  ****************************************************************************/
33 
34 /**
35  * @file dataman.h
36  *
37  * DATAMANAGER driver.
38  */
39 #pragma once
40 
41 #include <string.h>
42 #include <navigator/navigation.h>
43 #include <uORB/topics/mission.h>
44 
45 #ifdef __cplusplus
46 extern "C" {
47 #endif
48 
49 /** Types of items that the data manager can store */
50 typedef enum {
51  DM_KEY_SAFE_POINTS = 0, /* Safe points coordinates, safe point 0 is home point */
52  DM_KEY_FENCE_POINTS, /* Fence vertex coordinates */
53  DM_KEY_WAYPOINTS_OFFBOARD_0, /* Mission way point coordinates sent over mavlink */
54  DM_KEY_WAYPOINTS_OFFBOARD_1, /* (alternate between 0 and 1) */
55  DM_KEY_WAYPOINTS_ONBOARD, /* Mission way point coordinates generated onboard */
56  DM_KEY_MISSION_STATE, /* Persistent mission state */
58  DM_KEY_NUM_KEYS /* Total number of item types defined */
59 } dm_item_t;
60 
61 #if defined(MEMORY_CONSTRAINED_SYSTEM)
62 enum {
70 };
71 #else
72 /** The maximum number of instances for each item type */
73 enum {
81 };
82 #endif
83 /** Data persistence levels */
84 typedef enum {
85  DM_PERSIST_POWER_ON_RESET = 0, /* Data survives all resets */
86  DM_PERSIST_IN_FLIGHT_RESET, /* Data survives in-flight resets only */
87  DM_PERSIST_VOLATILE /* Data does not survive resets */
89 
90 /** The reason for the last reset */
91 typedef enum {
92  DM_INIT_REASON_POWER_ON = 0, /* Data survives resets */
93  DM_INIT_REASON_IN_FLIGHT, /* Data survives in-flight resets only */
94  DM_INIT_REASON_VOLATILE /* Data does not survive reset */
96 
98  uint64_t key;
99 };
100 
101 /* increment this define whenever a binary incompatible change is performed */
102 #define DM_COMPAT_VERSION 2ULL
103 
104 #define DM_COMPAT_KEY ((DM_COMPAT_VERSION << 32) + (sizeof(struct mission_item_s) << 24) + \
105  (sizeof(struct mission_s) << 16) + (sizeof(struct mission_stats_entry_s) << 12) + \
106  (sizeof(struct mission_fence_point_s) << 8) + (sizeof(struct mission_safe_point_s) << 4) + \
107  sizeof(struct dataman_compat_s))
108 
109 /** Retrieve from the data manager store */
110 __EXPORT ssize_t
111 dm_read(
112  dm_item_t item, /* The item type to retrieve */
113  unsigned index, /* The index of the item */
114  void *buffer, /* Pointer to caller data buffer */
115  size_t buflen /* Length in bytes of data to retrieve */
116 );
117 
118 /** write to the data manager store */
119 __EXPORT ssize_t
120 dm_write(
121  dm_item_t item, /* The item type to store */
122  unsigned index, /* The index of the item */
123  dm_persitence_t persistence, /* The persistence level of this item */
124  const void *buffer, /* Pointer to caller data buffer */
125  size_t buflen /* Length in bytes of data to retrieve */
126 );
127 
128 /**
129  * Lock all items of a type. Can be used for atomic updates of multiple items (single items are always updated
130  * atomically).
131  * Note that this lock is independent from dm_read & dm_write calls.
132  * @return 0 on success and lock taken, -1 on error (lock not taken, errno set)
133  */
134 __EXPORT int
135 dm_lock(
136  dm_item_t item /* The item type to lock */
137 );
138 
139 /**
140  * Try to lock all items of a type (@see sem_trywait()).
141  * @return 0 if lock is taken, -1 otherwise (on error or if already locked. errno is set accordingly)
142  */
143 __EXPORT int
144 dm_trylock(
145  dm_item_t item /* The item type to lock */
146 );
147 
148 /** Unlock all items of a type */
149 __EXPORT void
150 dm_unlock(
151  dm_item_t item /* The item type to unlock */
152 );
153 
154 /** Erase all items of this type */
155 __EXPORT int
156 dm_clear(
157  dm_item_t item /* The item type to clear */
158 );
159 
160 /** Tell the data manager about the type of the last reset */
161 __EXPORT int
162 dm_restart(
163  dm_reset_reason restart_type /* The last reset type */
164 );
165 
166 #if defined(FLASH_BASED_DATAMAN)
167 typedef struct dm_sector_descriptor_t {
168  uint8_t page;
169  uint32_t size;
170  uint32_t address;
171 } dm_sector_descriptor_t;
172 
173 /**
174  * Set the flash sector description were data should persist data
175  *
176  * Important: do not use a Flash sector from the same bank that STM32 read
177  * instructions or the CPU will held for sometime during Flash erase and write
178  * and this could cause your drone to fall.
179  */
180 __EXPORT int
181 dm_flash_sector_description_set(
182  const dm_sector_descriptor_t *description
183 );
184 #endif
185 
186 #ifdef __cplusplus
187 }
188 #endif
__EXPORT void dm_unlock(dm_item_t item)
Unlock all items of a type.
Definition: dataman.cpp:1202
dm_reset_reason
The reason for the last reset.
Definition: dataman.h:91
__EXPORT int dm_lock(dm_item_t item)
Lock all items of a type.
Definition: dataman.cpp:1157
Definition: I2C.hpp:51
__EXPORT int dm_restart(dm_reset_reason restart_type)
Tell the data manager about the type of the last reset.
Definition: dataman.cpp:1220
__EXPORT ssize_t dm_write(dm_item_t item, unsigned index, dm_persitence_t persistence, const void *buffer, size_t buflen)
write to the data manager store
Definition: dataman.cpp:1072
uint64_t key
Definition: dataman.h:98
dm_item_t
Types of items that the data manager can store.
Definition: dataman.h:50
__EXPORT int dm_clear(dm_item_t item)
Erase all items of this type.
Definition: dataman.cpp:1135
dm_persitence_t
Data persistence levels.
Definition: dataman.h:84
__EXPORT ssize_t dm_read(dm_item_t item, unsigned index, void *buffer, size_t buflen)
Retrieve from the data manager store.
Definition: dataman.cpp:1104
__EXPORT int dm_trylock(dm_item_t item)
Try to lock all items of a type (.
Definition: dataman.cpp:1179