User Manual Persistence Client Library Description

Transcription

Persistence Client Library
User Manual
Description
V 2.1
Date
September 11th, 2014
Copyright © 2014 XS Embedded GmbH
All rights reserved. No part of this document may be reproduced, stored in a
retrieval system, or transmitted in any form or by any means, without the prior
written permission of the publisher.
History
Rev.
V 1.0
V 1.1
V 1.2
Status
Draft
Draft
Draft
V 1.3
V 1.4
V 1.5
V 1.6
Draft
Draft
Draft
Draft
V 1.7
Draft
V 1.8
V 1.9
Draft
Draft
V 2.0
V 2.1
Draft
Released
Change
Setup of Document
Update after review
Update after review (split content into two
different documents, a user manual and a
architecture manual)
Added section default data handling
Added section roadmap of file API
Added section best practices
Added section to explain notification use;
added configure switch --enable-pasinterface
Added section 1.5 "Backup and recovery" and
1.6 "Caching Strategy"
Added section 7 Source Code Documentation
Added section 10.5 Backup Location and
updated section 9.1 Plugin interface (changed
configuration file format)
Added section 1.5.1
Updated section 5 How to build and 6 Testing
and Debugging
Date
nd
October 22 , 2013
th
November 6 , 2013
th
November 25 ,
2013
th,
December 11 2013
th,
January14 2014
th,
January17 2014
th
January 29 2014
th
April 1 2014
th
May 13 2014
th
June 26 2014
th
July 08 2014
th
September 11
2014
1
Table of Contents
1.
Persistence Subsystem ............................................................................................................ 7
1.1. GENIVI context .......................................................................................................................... 7
1.1.1.
Known issues ..................................................................................................................... 7
1.2.
Persistence Client Library License ......................................................................................... 7
1.3.
Key-value Database.................................................................................................................. 7
1.4.
API usage example ................................................................................................................... 8
1.5. Backup and Recovery Strategy ............................................................................................... 9
1.5.1.
Exclude files from backup ................................................................................................ 9
1.6. Caching Strategy ..................................................................................................................... 11
1.6.1.
File API ............................................................................................................................. 11
1.6.2.
Key-Value API.................................................................................................................. 11
2.
Persistence Client Library Interfaces ................................................................................... 12
2.1.
Application Programming Interface Description ................................................................. 12
2.2.
Data types ................................................................................................................................ 12
2.3. File API ..................................................................................................................................... 12
2.3.1.
pclFileClose Function ..................................................................................................... 13
2.3.2.
pclFileGetSize Function ................................................................................................. 13
2.3.3.
pclFileMapData ................................................................................................................ 14
2.3.4.
pclFileOpen ...................................................................................................................... 14
2.3.5.
pclFileReadData .............................................................................................................. 15
2.3.6.
pclFileRemove ................................................................................................................. 16
2.3.7.
pclFileSeek ....................................................................................................................... 16
2.3.8.
pclFileUnmapData ........................................................................................................... 17
2.3.9.
pclFileWriteData .............................................................................................................. 18
2.4. Key-Value API ......................................................................................................................... 19
2.4.1.
pclChangeNotifyCallback ............................................................................................... 19
2.4.2.
pclKeyDelete .................................................................................................................... 20
2.4.3.
pclKeyGetSize ................................................................................................................. 21
2.4.4.
pclKeyHandleClose ......................................................................................................... 22
2.4.5.
pclKeyHandleGetSize ..................................................................................................... 22
2.4.6.
pclKeyHandleOpen ......................................................................................................... 23
2.4.7.
pclKeyHandleReadData ................................................................................................. 24
2.4.8.
pclKeyHandleRegisterNotifyOnChange ....................................................................... 25
2.4.9.
pclKeyHandleWriteData ................................................................................................. 26
2
2.4.10. pclKeyReadData.............................................................................................................. 27
2.4.11. pclKeyRegisterNotifyOnChange ................................................................................... 28
2.4.12. pclKeyWriteData .............................................................................................................. 29
2.5.
Error definitions ....................................................................................................................... 30
2.6. Structures and enumerations for RCT ................................................................................. 32
2.6.1.
Policy enumerator ........................................................................................................... 32
2.6.2.
Storage enumerator ........................................................................................................ 32
2.6.3.
Resource type enumerator ............................................................................................ 32
2.6.4.
Structure definition of database context....................................................................... 33
2.6.5.
Permission enumerator .................................................................................................. 33
2.6.6.
Persistence configuration key structure ....................................................................... 33
2.6.7.
Resource configuration type structure ......................................................................... 34
2.6.8.
Persistence information structure ................................................................................. 34
2.6.9.
RCT type enumeration ................................................................................................... 34
3.
Notifications ............................................................................................................................. 35
3.1.
4.
5.
How the notification works ..................................................................................................... 35
Default data handling .............................................................................................................. 36
4.1.
Reading default data ............................................................................................................... 36
4.2.
Writing default data ................................................................................................................. 36
How to build.............................................................................................................................. 37
5.1.1.
6.
Dependencies .................................................................................................................. 37
Testing and Debugging .......................................................................................................... 38
6.1. Running the tests .................................................................................................................... 38
6.1.1.
Precondition ..................................................................................................................... 38
6.2.
Adding own user application .................................................................................................. 40
6.3.
Client Library database validation tool ................................................................................. 41
7.
Source Code Documentation ................................................................................................ 43
8.
Example Code .......................................................................................................................... 44
9.
Persistence Client Library Roadmap ................................................................................... 45
9.1. Plugin interface ........................................................................................................................ 45
9.1.1.
Plugin types ...................................................................................................................... 46
3
9.1.2.
9.1.3.
9.1.4.
9.2.
Loading type ..................................................................................................................... 46
Initialization type .............................................................................................................. 46
Plugin configuration file format ...................................................................................... 46
Function Overview .................................................................................................................. 47
9.3. Typedef Documentation ......................................................................................................... 48
9.3.1.
typedef int(* plugin_callback_async_t)(int errcode) ................................................... 48
9.3.2.
typedef int(* plugin_callback_t)(int, void *) .................................................................. 48
9.3.3.
typedef struct _plugin_info_s plugin_info_s ................................................................ 48
9.4. Function Documentation ........................................................................................................ 49
9.4.1.
int plugin_clear_all_data (void ) .................................................................................... 49
9.4.2.
int plugin_create_backup (const char * backup_id) ................................................... 49
9.4.3.
int plugin_deinit () ............................................................................................................ 50
9.4.4.
int plugin_delete_data (const char * path) ................................................................... 50
9.4.5.
int plugin_get_backup (char * backup_id, int size) ..................................................... 50
9.4.6.
int plugin_get_data (const char * path, char * buffer, int size) .................................. 51
9.4.7.
int plugin_get_info (plugin_info_s * pInfo_out) ............................................................ 51
9.4.8.
int plugin_get_size (const char * path) ......................................................................... 51
9.4.9.
int plugin_get_status_notification_clbk (plugin_callback_t pFunct) ......................... 52
9.4.10. int plugin_handle_close (int handle) ............................................................................. 52
9.4.11. int plugin_handle_get_data (int handle, char * buffer, int size) ................................ 52
9.4.12. int plugin_handle_get_size (int handle) ....................................................................... 53
9.4.13. int plugin_handle_open (const char * path, int flag, int mode) ................................. 53
9.4.14. int plugin_handle_set_data (int handle, char * buffer, int size)................................. 53
9.4.15. int plugin_init () ................................................................................................................ 54
9.4.16. int plugin_init_async (plugin_callback_async_t pfInitCompletedCB) ...................... 54
9.4.17. int plugin_restore_backup (const char * backup_id) .................................................. 54
9.4.18. int plugin_set_data (const char * path, char * buffer, int size) .................................. 55
9.4.19. int plugin_sync (void ) ..................................................................................................... 55
9.5. Administration functions ......................................................................................................... 56
9.5.1.
Defines .............................................................................................................................. 56
9.5.2.
pclInitLibrary ..................................................................................................................... 56
9.5.3.
pclDeinitLibrary ................................................................................................................ 57
9.6. File API functions .................................................................................................................... 58
9.6.1.
pclFileCreatePath ............................................................................................................ 58
9.6.2.
pclFileReleasePath ......................................................................................................... 59
10.
Best practice ......................................................................................................................... 60
10.1.
The resource configuration table customID .................................................................... 60
4
10.2.
The pclInitLibrary function and shutdown mode ............................................................. 60
10.3.
Shared data .......................................................................................................................... 60
10.4.
User and seat identifier in the API .................................................................................... 60
10.5.
Backup Location .................................................................................................................. 61
11.
Persistence Usability Rules ............................................................................................... 62
11.1.
Complete usage of the PCL (pclFileOpen .. pclFileClose)............................................ 62
11.2.
Usage of the PCL with pclFileCreatePath / pclFileReleasePath .................................. 62
11.3.
Free access persistence data ........................................................................................... 62
12.
Appendix ............................................................................................................................... 63
5
Table of Figures
Recovery Algorithm 1
API usage examples 2
10
12
Table Directory
8
6
1.
Persistence Subsystem
The scope of this document covers detailed interface description, building the library,
component testing and debugging.
1.1.
GENIVI context
The persistence client library has been developed as a proof of concept (PoC) for GENIVI.
PCL project homepage:
• http://projects.genivi.org/persistence-client-library
GENIVI git repository
• http://git.projects.genivi.org/?p=persistence/persistence-clientlibrary.git;a=summary
1.1.1.
Known issues
As
stated
above
the
implementation
is
a
proof
of
concept.
It is not intended that this implementation of the client library is used in a real project, as per
definition of a PoC is only demonstrate the feasibility of chosen aspects of the specification.
There are some issues with the used Itzam/C database engine, e.g. it does not do any
caching and this will potentially lead to wear out issues. This is the default storage
implementation of the Persistence Common Object.
Itzam/C will soon be removed by a solution that solves the wear out issues.
1.2.
Persistence Client Library License
The Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0. If a copy
of the MPL was not distributed with this file. You can obtain one at
http://mozilla.org/MPL/2.0/.
1.3.
Key-value Database
A key value database is not anymore part of the PCL. The database has been moved to a
separate library called Persistence Common Object (libperscommon). The advantage is to
allow the implementation of different key-value databases engines which can be used by the
PCL and database functionality is also needed by the Persistence Administration Service.
The Persistence Common Object (PCO) is available on the following GENIVI git repository:
http://git.projects.genivi.org/?p=persistence/persistence-common-object.git;a=summary
7
1.4.
API usage example
Interface prototype:
int pclKeyWriteData(
unsigned int ldbid,
const char* resource_id,
unsigned int user_no,
unsigned char seat_no,
unsigned char* buf,
unsigned long size)
The following table gives you examples about the parameters usage in different locations of
the key-value management.
Persistence Client API
Persistence lib (from client resource
table)
data base "input"
Comment
0xFF, "/pos/last pos", 0, 0
"/Data/mnt-c/Appl-1/cached.itz"
"/Node/pos/last pos"
0, "/language/cur_lang", 3, 0
"/Data/mnt-wt/Shared/Public/wt.itz"
"/User/3/language/cur_lang"
0xFF, "/status/op_doc", 3, 2
"/Data/mnt-c/Appl-1/cached.itz"
"/User/3/Seat/2/status/op_doc"
20, "/address/home_addr, 4, 0
"/User/4/address/home_addr"
0xFF, "/pos/last sat", 0, 0
"/Data/mntc/Shared/Group/20/cached.itz"
"/Data/mnt-wt/Appl-1/wt.itz"
"/Node/pos/last satellites"
0x84, "/links/last link", 2, 0
"/Data/mnt-wt/Appl-2/wt.itz"
"/84/User/2/links/last link"
local value (last
position)
public shared user value
(current_language)
local user seat value
(open_document)
group shared user value
( home address)
local value (last
satellites)
local value (last link)
0xFF "/media/mediaDB.db", 1, 1
"/Data/mnt-c/Appl-1/"
"/User/1/Seat/1/mediaDb.db"
local file
The resolution from the given API parameters to the key-value data or the file is done in
done the following way:
1. The lbid parameter gives a hint which resource configuration table (RCT) to use
a. First the RCT in the cached path will be queried
b. If the resource can be found in the RCT the storage policy will be queried
c. If storage policy is cached use the database in the cached path otherwise in
the write through path.
d. 0xFFFF
application local data, use the RCT in the application folder
e. 0x0
public data, use RCT in the shared folder
f. E.g. group 20
use the RCT in the group folder of group 20
2. Then the input "key" to the database will be generated using resourceId, user_no
and seat_no
a. User 0 and seat 0
it is NODE data
input string is /Node/resourceID
b. User 3 and seat 2 it is USER data bound to a SEAT
/User/3/Seat2/resourceID
8
1.5.
Backup and Recovery Strategy
A backup copy of the file including the generation of a checksum file is created when the file
is modified the first time (Copy-on-write). There is no backup created if the file will only be
read.
The checksum file is used during recovery to ensure that the backup copy is not corrupt.
A backup copy is created only once during the lifecycle and is removed during the shutdown
phase when an application has successfully written the data using pclFileWriteData and
calls writing the file back to non-volatile memory device (e.g. eMMC).
When writing the file back to e.g. eMMC the backup and checksum files are deleted. This is
an indicator that the system has been shut down correctly. If the PCL detects in a new
lifecycle that there is a backup and/or a checksum file available this is an indicator that the
system hasn't been shut down correctly and the files must be checked for consistency.
Note:
A system failure which ends up in a restart of the system can occur at any time within a
lifecycle.
One critical path is during the pclFileWriteData function call, where the checksum is
calculated and stored and the backup file is created.
The other critical path in the shutdown phase, where the backup file and the checksum files
are deleted and the file is transferred from the RAM to the non-volatile storage device.
To cover this "reset" scenarios in the best way, there are some assumptions on the
pclFileOpen function, where we try to detect such system failures and do a best guess to
react properly. The following sequence diagram explains the recovery algorithm.
1.5.1.
Exclude files from backup
It is possible to exclude files from the backup mechanism. For this reason there is the file
BackupFileList.info in each application folder. Add the relative path and filename to this file
and it will be excluded from the backup creation.
Example:
BackupFileList.info location:
/Data/mnt-c/lt-persistence_client_library_test/BackupFileList.info
File content:
/media/mediaDatabase.db
File to Exclude:
/Data/mnt-c/lt-persistence_client_library_test/user/X/seat/Y/media/mediaDatabase.db
Note: The file will be excluded from the backup for every user on each seat.
9
Recovery Algorithm 1
10
1.6.
Caching Strategy
1.6.1.
File API
Files accessed via the file API will be cached using the Persistence File Cache Component.
The files are transferred into the cache when it is modified the first time (copy-on-write concept).
All further access to the files (read/write) will only affect the files kept in the cache.
For more details about this component please refer to the Persistence File Cache User Manual.
1.6.2.
Key-Value API
Caching of the key-value pairs is not in scope of the PCL.
The database for the key-value pairs is implemented in the Persistence Common Object (PCO).
For more details about the database engine please refer to the PCO documentation.
11
2.
Persistence Client Library Interfaces
2.1.
Application Programming Interface Description
The Persistence Client Library provides a C-API for applications allowing loading and storing
persistent data. The API is divided into two main parts, the key-value API and the file API.
2.2.
Data types
The PCL does not support storing of any complex data structures or any other data types
than unsigned char*.
It was a design decision not to support data type families like e.g. glib or Qt data types or
other complex custom data structures as they all can be stored using the unsigned char*
data type. Serialization/deserialization or casting must be done by the using application.
2.3.
File API
The Persistence Client Library offers two sorts of functions for the Key-value and file
interface to read and write data, handle functions and non-handle functions.
For the handle functions first the open function (pclKeyHandleOpen) needs to be called,
and then using the handle the corresponding read/write (e.g. pclKeyHandleReadData)
function can be called.
If requested to just read or write only once to a resource non-handle functions are also
available (e.g. pclKeyReadData).
Note:
A file will not be identified directly by a file system path when using for example the
pclFileOpen function. The logical database ID, the resource ID, the user ID and the seat
ID will be translated into a path and a filename within the file system hierarchy.
12
2.3.1.
pclFileClose Function
The pclFileClose function closes the given POSIX file descriptor.
Syntax
int pclFileClose
(
int fd
);
fd the file descriptor to close
Parameters
fd
The POSIX file descriptor
Return Value
Zero on success.
On error a negative value will be returned with the following error codes:
EPERS_LOCKFS EPERS_COMMON.
If EPERS_COMMON will be returned errno will be set.
2.3.2.
pclFileGetSize Function
The function pclFileGetSize returns the size of the file given by the file descriptor
Syntax
int pclFileGetSize
(
int fd
);
Parameters
fd
The POSIX file descriptor
Return Value
Success a positive value will be returned.
On error EPERS_NOT_INITIALIZED or EPERS_COMMON will be returned.
13
2.3.3.
pclFileMapData
The function pclFileMapData maps a file into memory
Syntax
void* pclFileMapData
(
void* addr,
long size,
long offset,
int fd
);
Parameters
addr
if NULL, kernel chooses address
size
the size in bytes to map into the memory
offset
in the file to map
fd
the POSIX file descriptor of the file to map
Return Value
Returns a pointer to the mapped area, or on error the value MAP_FAILED or
EPERS_MAP_FAILEDLOCK if file system is currently locked
2.3.4.
pclFileOpen
The pclFileOpen function opens a file and returns a POSIX file descriptor.
Syntax
int pclFileOpen
(
unsigned int ldbid,
unsigned int seat_no
);
Parameters
ldbid
logical database ID
resource_id
the resource ID
14
user_no
user_no=0 cannot be used as user-ID because ‘0’ is defined as System/node
seat_no
the seat number
Return Value
A positive value (0 or greater): the POSIX file descriptor;
EPERS_LOCKFS, EPERS_MAXHANDLE, EPERS_NOKEY, EPERS_NOKEYDATA,
EPERS_NOPRCTABLE, EPERS_NOT_INITIALIZED, EPERS_COMMON
Remarks
The user_no and seat_no will be provided by user management.
2.3.5.
pclFileReadData
The function pclFileReadData reads persistent data from a file.
Syntax
int pclFileReadData
(
int fd,
void * buffer,
int buffer_size
);
Parameters
fd
POSIX file descriptor
buffer
buffer to read the data
buffer_size
the size buffer for reading
Return Value
A positive value (0 or greater): the size read;
EPERS_NOT_INITIALIZED, EPERS_LOCKFS, EPERS_COMMON.
If EPERS_COMMON will be returned errno will be set
15
2.3.6.
pclFileRemove
The function pclFileRemove removes the file.
Syntax
int pclFileRemove
(
unsigned int ldbid,
);
Parameters
ldbid
logical database ID
resource_id
the resource ID
user_no
the user ID; user_no=0 cannot be used as user-ID because ‘0’ is defined as
System/node
seat_no
the seat number
Return Value
Positive value (0 or greater): success;
EPERS_NOT_INITIALIZED, EPERS_LOCKFS, EPERS_COMMON.
If ::EPERS_COMMON will be returned errno will be set
Remarks
2.3.7.
pclFileSeek
The function pclFileSeek repositions the file descriptor.
Syntax
int pclFileSeek
(
int fd,
long int offset,
int whence
);
16
Parameters
fd
the POSIX file descriptor
offset
the reposition offset
whence
the direction to reposition
SEEK_SET
The offset is set to offset bytes.
SEEK_CUR
The offset is set to its current location plus offset bytes.
SEEK_END
The offset is set to the size of the file plus offset bytes.
Return Value
A positive value (0 or greater): resulting offset location;
EPERS_LOCKFS, EPERS_NOT_INITIALIZED, EPERS_COMMON.
If ::EPERS_COMMON will be returned errno will be set
2.3.8.
pclFileUnmapData
The function pclFileUnmapData unmaps the file form the memory
Syntax
int pclFileUnmapData
(
void* address,
long size
);
Parameters
address
the address to unmap
size
the size in bytes to unmap
Return Value
Returns on success 0;
EPERS_LOCKFS, EPERS_NOT_INITIALIZED, EPERS_COMMON.
If EPERS_COMMON will be returned errno will be set
17
2.3.9.
pclFileWriteData
The function pclFileWriteData writes persistent data to file
Syntax
int pclFileWriteData
(
int fd,
const void * buffer,
int buffer_size
);
Parameters
fd
the POSIX file descriptor
buffer
the buffer to write
buffer_size
the size of the buffer to write in bytes
Return Value
A positive value (0 or greater) the bytes written;
EPERS_LOCKFS, EPERS_NOT_INITIALIZED or EPERS_COMMON
18
2.4.
Key-Value API
2.4.1.
pclChangeNotifyCallback
The pclChangeNofityCallback is the definition of the change callback
Syntax
typedef int(* pclChangeNotifyCallback_t)(pclNotification_s *
notifyStruct);
Parameters
notifyStruct
structure for notification
Return Value
A positive value on success;
On error a negative value will be returned with the following error codes: EPERS_LOCKFS
Remarks
/**
* Structure to return in case of notification
*/
typedef struct _pclNotification_s
{
pclNotifyStatus_e pclKeyNotify_Status;
///
unsigned int ldbid;
///
const char * resource_id;
///
unsigned int user_no;
///
unsigned int seat_no;
///
} pclNotification_s;
notification status
logical db id
resource id
user id
seat id
/**
* Status returned in notification structure
*/
typedef enum _pclNotifyStatus_e
{
pclNotifyStatus_no_changed = 0,
pclNotifyStatus_created,
pclNotifyStatus_changed,
pclNotifyStatus_deleted,
/* insert new_ entries here .. */
pclNotifyStatus_lastEntry
} pclNotifyStatus_e;
19
2.4.2.
pclKeyDelete
The function pclKeyDelete will delete a persistent data key form the database
Syntax
int pclKeyDelete
(
unsigned int ldbid,
);
Parameters
ldbid
logical database ID
resource_id
the resource ID
user_no
System/node
seat_no
the seat number
Return Value
A positive value (0 or greater): success;
EPERS_LOCKFS, EPERS_NOTIFY_SIG, EPERS_NOT_INITIALIZED, EPERS_BADPOL
Remarks
20
2.4.3.
pclKeyGetSize
The function pclKeyGetSize returns the size of persistent data in bytes
Syntax
int pclKeyGetSize
(
unsigned int ldbid,
);
Parameters
ldbid logical
database ID
resource_id
the resource ID
user_no
System/node
seat_no
the seat number
Return Value
A positive value (0 or greater): the size;
EPERS_LOCKFS,
EPERS_BADPOL,
EPERS_NOKEY,
EPERS_NOKEYDATA,
EPERS_NOPRCTABLE, EPERS_NOT_INITIALIZED
Remarks
21
2.4.4.
pclKeyHandleClose
The function pclKeyHandleClose closes the access to a key-value identified by key handle
Syntax
int pclKeyHandleClose
(
int key_handle
);
Parameters
key_handle
key value handle returned by key_handle_open()
Return Value
A positive value (0 or greater) on success;
EPERS_LOCKFS, EPERS_MAXHANDLE, EPERS_NOPLUGINFUNCT,
EPERS_NOT_INITIALIZED
2.4.5.
pclKeyHandleGetSize
The function pclKeyHandleGetSize gets the size of persistent data in bytes identified by key
handle.
Syntax
int pclKeyHandleGetSize
(
int key_handle
);
Parameters
key_handle
key value handle return by key_handle_open()
Return Value
A positive value (0 or greater) is the size;
EPERS_NOT_INITIALIZED, EPERS_LOCKFS, EPERS_NOPLUGINFUNCT,
EPERS_MAXHANDLE, EPERS_NOKEY, EPERS_DB_KEY_SIZE, EPERS_NOPRCTABLE
22
2.4.6.
pclKeyHandleOpen
The function pclKeyHandleOpen open a handle to a key-value
Syntax
int pclKeyHandleOpen
(
unsigned int ldbid,
);
Parameters
ldbid
logical database ID
resource_id
the resource ID
user_no
System/node
seat_no
the seat number
Return Value
A positive value (0 or greater) is the key handle to access the value;
EPERS_NOT_INITIALIZED, EPERS_NOPLUGINFUNCT
Remarks
23
2.4.7.
pclKeyHandleReadData
The function pclKeyHandleReadData reads persistent data identified by key handle
Syntax
int pclKeyHandleReadData
(
int key_handle,
unsigned char* buffer,
int buffer_size
);
Parameters
key_handle
buffer
the buffer for persistent data
buffer_size
size of buffer for reading
Return Value
A positive value (0 or greater) is the bytes read;
EPERS_NOT_INITIALIZED, EPERS_NOPLUGINFUNCT, EPERS_MAXHANDLE
24
2.4.8.
pclKeyHandleRegisterNotifyOnChange
The function pclKeyHandleRgisterNotifyOnChange registers a change notification for
persistent data
Syntax
int pclKeyHandleRegisterNotifyOnChange
(
int key_handle,
pclChangeNotifyCallback_t callback
);
Parameters
key_handle
callback
notification callback
Return Value
A positive value (0 or greater) means the registration succeeded;
EPERS_NOT_INITIALIZED, EPERS_MAXHANDLE, EPERS_NOTIFY_NOT_ALLOWED
Remarks
It is only possible to register for change notification for shared data, otherwise registration
fails.
For more details see chapter 3.1.
25
2.4.9.
pclKeyHandleWriteData
The function pclKeyHandleWriteData writes persistent data identified by key handle
Syntax
int pclKeyHandleWriteData
(
int key_handle,
int buffer_size
);
Parameters
key_handle
buffer
the buffer containing the persistent data to write
buffer_size
the number of bytes to write (default max size is set to 16kB) use environment variable
PERS_MAX_KEY_VAL_DATA_SIZE to modify default size in bytes
Return Value
A positive value (0 or greater): the bytes written;
EPERS_LOCKFS, EPERS_MAX_BUFF_SIZE, EPERS_NOTIFY_SIG,
EPERS_DB_VALUE_SIZE, EPERS_DB_KEY_SIZE, EPERS_NOPRCTABLE
EPERS_DB_VALUE_SIZE
26
2.4.10. pclKeyReadData
The function pclKeyReadData reads persistent data identified by ldbid and resource_id
Syntax
int pclKeyReadData
(
unsigned int ldbid,
unsigned int seat_no,
int buffer_size
);
Parameters
ldbid
logical database ID
resource_id
the resource ID
user_no
System/node
seat_no
the seat number
buffer
the buffer to read the persistent data
buffer_size
size of buffer for reading
Return Value
A positive value (0 or greater): the bytes read;
EPERS_LOCKFS, EPERS_NOT_INITIALIZED, EPERS_BADPOL,
EPERS_NOPLUGINFUNCT
Remarks
27
2.4.11. pclKeyRegisterNotifyOnChange
The function pclKeyRegisterNotifyOnChange registers a change notification callback for
persistent data
Syntax
int pclKeyRegisterNotifyOnChange
(
unsigned int ldbid,
pclChangeNotifyCallback_t callback
);
Parameters
ldbid
logical database ID of the resource to monitor
resource_id
the resource ID
user_no
the user ID; user_no=0 cannot be used as user-ID beacause ‘0’ is defined as
System/node
seat_no
the seat number
callback
notification callback
Return Value
A positive value (0 or greater): registration OK;
EPERS_RES_NO_KEY, EPERS_NOKEYDATA, EPERS_NOPRCTABLE,
EPERS_NOTIFY_NOT_ALLOWED
Remarks
It is only possible to register for change notification for shared data, otherwise registration
fails.
For more details see chapter 3.1.
28
2.4.12. pclKeyWriteData
The function pclKeyWriteData writes persistent data identified by ldbid and resource_id
Syntax
int pclKeyWriteData
(
unsigned int ldbid,
int buffer_size
);
Parameters
ldbid
logical database ID
resource_id
the resource ID
user_no
System/node
seat_no
the seat number
buffer
the buffer containing the persistent data to write
buffer_size
the number of bytes to write (default max size is set to 16kB)
use environment variable PERS_MAX_KEY_VAL_DATA_SIZE to modify default size in
bytes
Return Value
A positive value (0 or greater): the bytes written;
EPERS_LOCKFS, EPERS_BADPOL, EPERS_BUFLIMIT, EPERS_DB_VALUE_SIZE,
EPERS_DB_KEY_SIZE, EPERS_NOTIFY_SIG
Remarks
29
2.5.
Error definitions
This section shows the defined errors codes that are available for the persistence client
library.
/// common error, for this error errno will be set
#define EPERS_COMMON
(-1)
/// file system is locked
#define EPERS_LOCKFS
(-2)
/// filesystem is currently locked
#define EPERS_MAP_LOCKFS
((void *) -2)
/// bad storage policy
#define EPERS_BADPOL
(-3)
/// open handle limit reached
#define EPERS_MAXHANDLE
(-4)
/// max buffer limit for persistence data
#define EPERS_BUFLIMIT
(-5)
/// persistence resource configuration table not found
#define EPERS_NOPRCTABLE
(-6)
/// key not found
#define EPERS_NOKEY
(-7)
/// no data for key
#define EPERS_NOKEYDATA
(-8)
/// write of data failed
#define EPERS_SETDTAFAILED
(-9)
/// failed to open file
#define EPERS_OPENFILE
(-10)
/// invalid buffer or key
#define EPERS_DESER_BUFORKEY
(-11)
/// can't allocat memory for deserialization of keyvalue
#define EPERS_DESER_ALLOCMEM
(-12)
/// no ploicy avaliable in data to serialize
#define EPERS_DESER_POLICY
(-13)
/// no store type avaliable in data to serialize
#define EPERS_DESER_STORE
(-14)
/// no permission avaliable in data to serialize
#define EPERS_DESER_PERM
(-15)
/// no max size avaliable in data to serialize
#define EPERS_DESER_MAXSIZE
(-16)
/// no responsibility avaliable in data to serialize
#define EPERS_DESER_RESP
(-17)
/// out of array bounds
#define EPERS_OUTOFBOUNDS
(-18)
/// failed to map config file
30
#define EPERS_CONFIGMAPFAILED
(-19)
/// config file if not available
#define EPERS_CONFIGNOTAVAILABLE (-20)
/// can't stat config file
#define EPERS_CONFIGNOSTAT
(-21)
/// plugin functin not found
#define EPERS_NOPLUGINFCNT
(-22)
/// dlopen error
#define EPERS_DLOPENERROR
(-23)
/// plugin function not loaded
#define EPERS_NOPLUGINFUNCT
(-24)
/// file remove error
#define EPERS_FILEREMOVE
(-25)
/// err code to signalize last entry in DB
#define EPERS_LAST_ENTRY_IN_DB
(-26)
/// internal database error
#define EPERS_DB_ERROR_INTERNAL (-27)
/// db key size is to long
#define EPERS_DB_KEY_SIZE
(-28)
/// db value size is to long
#define EPERS_DB_VALUE_SIZE
(-29)
/// resource is not a key
#define EPERS_RES_NO_KEY
(-30)
/// change notification signal could ne be sent
#define EPERS_NOTIFY_SIG
(-31)
/// client library has not been initialized
#define EPERS_NOT_INITIALIZED
(-32)
// max buffer size
#define EPERS_MAX_BUFF_SIZE
(-33)
// failed to setup dbus mainloop
#define EPERS_DBUS_MAINLOOP
(-34)
// failed register lifecycle dbus
#define EPERS_REGISTER_LIFECYCLE (-35)
// failed register admin service dbus
#define EPERS_REGISTER_ADMIN
(-36)
// registration on this key is not allowed
#define EPERS_NOTIFY_NOT_ALLOWED (-37)
// the requested resource is not a file
#define EPERS_RESOURCE_NO_FILE
(-38)
31
2.6.
Structures and enumerations for RCT
This chapter describes the used structure and enumeration definitions.
2.6.1.
Policy enumerator
/// enumerator used to identify the policy
typedef enum _PersistencePolicy_e
{
PersistencePolicy_wc = 0, /// the data
PersistencePolicy_wt = 1, /// the data
PersistencePolicy_na = 2, /// the data
/** insert new entries here ... */
PersistencePolicy_LastEntry
///
to manage the data
is managed write cached
is managed write through
is not applicable
last entry
} PersistencePolicy_e;
2.6.2.
Storage enumerator
/// enumerator used to identify the persistence storage to manage
the data
typedef enum _PersistenceStorage_e
{
PersistenceStorage_local = 0, /// the data is managed local
PersistenceStorage_shared = 1, /// the data is managed shared
PersistenceStorage_custom = 2, /// the data is managed over
/// custom client implementation
PersistenceStorage_LastEntry
/// last entry
} PersistenceStorage_e;
2.6.3.
Resource type enumerator
/** specify the type of the resource */
typedef enum PersistenceResourceType_e_
{
PersistenceResourceType_key = 0, /// key type resource
PersistenceResourceType_file,
/// file type resource
PersistenceResourceType_LastEntry /// last entry
} PersistenceResourceType_e;
32
2.6.4.
Structure definition of database context
/// structure used to manage database context
typedef struct _PersistenceDbContext_s
{
unsigned int ldbid;
/// logical database identifier
unsigned int user_no;
/// user number
unsigned int seat_no;
/// seat number
} PersistenceDbContext_s;
2.6.5.
Permission enumerator
typedef enum PersistencePermission_e_
{
PersistencePermission_ReadWrite = O_RDWR,
PersistencePermission_ReadOnly = O_RDONLY,
PersistencePermission_WriteOnly = O_WRONLY,
PersistencePermission_LastEntry
/// last entry
} PersistencePermission_e;
2.6.6.
Persistence configuration key structure
/// structure used to manage the persistence configuration for a key
typedef struct _PersistenceConfigurationKey_s
{
/// policy
PersistencePolicy_e
policy;
/// definition of storage to use
PersistenceStorage_e storage;
/// type of the resource
PersistenceResourceType_e type;
/// file access flags
PersistencePermission_e
permission;
/// max size expected for the key
unsigned int
max_size;
/// name of responsible app
char reponsible[MaxConfKeyLengthResp];
/// name of the customer plugin
char custom_name[MaxConfKeyLengthCusName];
/// internal ID for the custom type resource
char customID[MaxRctLengthCustom_ID];
} PersistenceConfigurationKey_s;
33
2.6.7.
Resource configuration type structure
/// structure definition of a persistence resource configuration
/// table entry
typedef struct _PersistenceRctEntry_s
{
char key[PrctKeySize];
/// the key
PersistenceConfigurationKey_s data;
/// data for the key
}
PersistenceRctEntry_s;
2.6.8.
Persistence information structure
/// persistence information
typedef struct _PersistenceInfo_s
{
PersistenceDbContext_s
context;
PersistenceConfigurationKey_s configKey;
} PersistenceInfo_s;
2.6.9.
/// database context
/// rct config key
RCT type enumeration
/// persistence resource configuration table type definition
typedef enum _PersistenceRCT_e
{
PersistenceRCT_local
= 0,
PersistenceRCT_shared_public = 1,
PersistenceRCT_shared_group = 2,
PersistenceRCT_LastEntry
/// last Entry
} PersistenceRCT_e;
34
3.
Notifications
The persistence client library provides a notification mechanism to inform applications if a key
has been created, changed or deleted by another application. Registering to a notification is
only possible on shared data.
A notification mechanism on files is not provided by the PCL, it is recommended to use
inotify to monitor file system events the get the information.
3.1.
How the notification works
An application interested in notifications about the status change of particular key of another
application can register itself to get this information.
The key API provides two functions, pclKeyHandleRegisterNotifyOnChange and
pclKeyRegisterNotifyOnChange.
Both functions have the parameter pclChangeNotifyCallback_t callback, which is a
function pointer to a callback function.
This callback function will be called whenever the key under monitor changes its status, this
means the key's content will be changed or it will be created or deleted.
The notification function's parameter pclNotification_s notifyStruct can be used to
determine the kind of change.
The used IPC mechanism between the applications is dbus.
35
4.
Default data handling
Persistence has two different types of default data, the factory default data and the configurable
default data.
4.1.
Reading default data
The PCL has no special interface to read and write default data.
If an application wants to read the data of a resource the PCL is doing this in the following way:
• first try read the data for the resource, if available return this data
• if no data is available, check if configurable default data available and return
this data
• if no configurable default data is available, check if there is factory default data
is available, and return this data.
• If still no data is available return an error.
4.2.
Writing default data
Factory default data can't be changed, but configurable default data can be adjusted.
Setting data back to factory default data or to configurable data can't be done using the PCL
API, instead the Persistence Administration Service API needs to be used.
For more details see PAS API documentation, especially the following function:
long persAdminDataRestore(PersASSelectionType_e type,
PersASDefaultSource_e defaultSource,
const char* applicationID,
unsigned int seat_no);
36
5.
How to build
The Persistence Client Lib component uses automake to build the library.
Execute the following steps in order to build the component
• autoreconf –vi
• configure, with the following options
o –enable-tests
to enable the build of the tests
o --enable-pasinterface
enable the PAS interface (disabled by default)
o "-- with_database
decide which storage backend to use
Itzam/C is currently default backend
It is recommended to use the key-value-store backend
• "-- with_database=key-value-store"
• make
5.1.1.
Dependencies
The client library has the following dependencies
• Libraries
o automotive-dlt
http://projects.genivi.org/diagnostic-log-trace/
o Libperscommon
http://git.projects.genivi.org/?p=persistence/persistence-commonobject.git;a=summary
Add "-- with_database=key-value-store" to the configure step
o dbus-1
o check unit test framework for C
used when configured with "--enable-tests"
Ubuntu: use Synaptic package manager
Or download http://check.sourceforge.net/
•
•
autotools
libtool
37
6.
Testing and Debugging
The test framework “check” has been used to write unit tests which will be run automatically
when the test binary will be started. At the end a test report will be printed to the console
showing first a summary about number of tests that have been executed and how many
tests have been passed or failed. After the summary a test report will be generated showing
the status of each test. When a bug will be fixed a test will be written to verify the problem
has been solved.
DTL (Diagnostic, Log and Trace) will be used by the PCL to send status and error. For
details
about
DLT,
please
refer
to
the
GENIVI
DLT
project
page
(http://projects.genivi.org/diagnostic-log-trace/).
6.1.
Running the tests
There are unit tests available for the persistency client library component available.
The unit tests are used to verify that the component is working correctly and exclude any
regressions. Please refer always to the source code to see the available tests.
6.1.1.
Precondition
•
•
•
•
•
•
•
GENIVI Lifecycle components are available on the system
o The GENIVI lifecycle components are available here:
http://projects.genivi.org/node-state-manager/
http://projects.genivi.org/node-startup-controller/
o Make sure Node State Manager is running
Start "node-state-manager"
Persistence Administration Service is available in the system and running
o The GENIVI Persistence Administration Service is available here:
http://git.projects.genivi.org/?p=persistence/persistenceadministrator.git
Persistence Common Object is available in the system
o The GENIVI Persistence Common Object is available here:
http://git.projects.genivi.org/?p=persistence/persistence-commonobject.git
o use the key-value-store backend
run configure step with "-- with_database=key-value-store"
Persistence partitions has been created and mounted and test data is
If partition and data is not available, use the PAS to setup the test data.
o make sure node-state-manager and pers_admin_svc are running
o Now install the test data:
"persadmin_tool install /path_to_test_data/PAS_data.tar.gz"
The test data is provided by the PCL (../test/data/PAS_data.tar.gz)
Make sure dlt-daemon is running
Make sure D-Bus system bus is available
38
Run test
•
run persistency unit test "./persistence_client_library_test"
Expected Result
The expected result is to have 0 failures and 0 errors, see example output below:
./persistence_client_library_test
Running suite(s): Persistency client library
100%: Checks: 13, Failures: 0, Errors: 0
persistence_client_library_test.c:141:P:GetData:test_GetData:0: Passed
persistence_client_library_test.c:357:P:SetData:test_SetData:0: Passed
persistence_client_library_test.c:400:P:SetDataNoPRCT:test_SetDataNoPRCT:0: Passed
persistence_client_library_test.c:434:P:GetDataSize:test_GetDataSize:0: Passed
persistence_client_library_test.c:478:P:DeleteData:test_DeleteData:0: Passed
persistence_client_library_test.c:236:P:GetDataHandle:test_GetDataHandle:0: Passed
persistence_client_library_test.c:652:P:DataHandle:test_DataHandle:0: Passed
persistence_client_library_test.c:727:P:DataHandleOpen:test_DataHandleOpen:0: Passed
persistence_client_library_test.c:578:P:DataFile:test_DataFile:0: Passed
persistence_client_library_test.c:604:P:DataFileRecovery:test_DataFileRecovery:0: Passed
persistence_client_library_test.c:794:P:Cursor:test_Cursor:0: Passed
persistence_client_library_test.c:864:P:ReadDefault:test_ReadDefault:0: Passed
persistence_client_library_test.c:886:P:ReadConfDefault:test_ReadConfDefault:0: Passed
The output above may vary as the test cases will be adopted or extended.
39
6.2.
Adding own user application
Normally the default file and folder structure including the default data as well as the RCT
and the database will be setup by the Persistence Administration Service.
If a user wants to extend the provided test application or create an own test application it can
be done without using the PAS to extend the file and folder structure.
An example could be a navigation application likes to use the PCL it can be done in the
following way:
Example Code:
int ret = 0;
unsigned char buffer[READ_SIZE] = {0};
unsigned int shutdownReg = PCL_SHUTDOWN_TYPE_FAST |
PCL_SHUTDOWN_TYPE_NORMAL;
// initialize PCL
pclInitLibrary("navigation", shutdownReg);
ret = pclKeyWriteData(0xFF, "mapSettings", 1, 2, "northUp",
strlen("northUp"));
ret = pclKeyReadData(0xFF, "mapSettings",
1, 2, buffer, READ_SIZE);
// do something
// end the usage of PCL
pclDeinitLibrary();
1. Use the PCL initialization function and provide the name of the application the PCL
should use. The example above uses the identifier "navigation"
2. Create a folder with the identifier name as used for the PCL init. Here the folder must
be named "navigation".
a. In this example the path must look like /Data/mnt-c/navigation/
3. Copy the existing RCT and database from the folder ltpersistence_client_library_test provided in the test data
a. Copy RCT file "resource-table-cfg.itz" into /Data/mnt-c/navigation
b. Copy the database "cached.itz" to /Data/mnt-c/navigation
4. Now you should be able to write and read data like shown in the example above.
a. Note: As there is no entry for this resource in the RCT, the resource will be
stored in the local cached path.
5. If another application wants to use the PCL, e.g. a tuner application, just proceed
step 1 to 3 using an appropriate name (e.g. tuner) as application name and folder
40
6.3.
Client Library database validation tool
This tool can be used to verify an executed action to the persistence databases. It provides
access to the persistence databases to read/write, delete and query the size of a key. This
allows an easy verification of the database content.
Note: This is not yet available as it is currently under development
Usage: persclient_tool [-o
[-r
[-u
[-p
<action to do>] [-a <application name>]
<resource id>] [-l <logical db id>]
<user no>] [-s <seat no>] [-f <file>]
<payload>] [-H] [-h] [-v]
-o, --option=<action to do>
-a, --appname=<application name>
-f, --file=<filename>
-p, --payload=<payload>
-r, --resource_id=<resource id>
-l, --ldbid=<logical db id>
-u, --user_no=<user no>
-s, --seat_no=<seat no>
-H, --forcehexdump
-h, --help
-V, --version
The possible actions are:
readkey
- read out the given
key
writekey
- write something to a
key
deletekey - delete a key
getkeysize - get the size of a
key
The Application Name used for the
initialization of the PCL
The file for data import or
export
The data to be written to a key
if no file is specified as
source.
The resource ID is the name of
the key to process
Logical Database ID in hex
notation! e.g. 0xFF. If not
specified the default value
'0xFF' is used
The user number. If not specified
the default value '0' is used
The seat number. If not specified
the default value '0' is used
Force print out a HexDump of the
written/read data
Print help message
Print program version
41
Examples:
1.) Read a Key and show value as HexDump:
persclient_tool -o readkey -a MyApplication -r MyKey
optional parameters: [-l 0xFF -u 0 -s 0]
2.) Read a Key into a file:
persclient_tool -o readkey -a MyApplication -r MyKey -f
outfile.bin
optional parameters: [-l 0xFF -u 0 -s 0 -H]
3.) Write a Key and use the <payload> as the data source.:
persclient_tool -o writekey -a MyApplication -r MyKey -p 'Hello
World' optional parameters: [-l 0xFF -u 0 -s 0 -H]
4.) Write a Key and use a file as the data source.:
persclient_tool -o writekey -a MyApplication -r MyKey -f
infile.bin
optional parameters: [-l 0xFF -u 0 -s 0 -H]
5.) Get the size of a key [bytes]:
persclient_tool -o getkeysize -a MyApplication -r MyKey
6.) Delete a key:
persclient_tool -o deletekey -a MyApplication -r MyKey
42
7.
Source Code Documentation
To generate source code documentation doxygen will be used.
Run the command "doxygen doc/pcl_doxyfile" and the html documentation will be generated
within the subfolder doc.
43
8.
Example Code
int ret = 0;
unsigned int shutdownReg = (PCL_SHUTDOWN_TYPE_FAST | PCL_SHUTDOWN_TYPE_NORMAL);
unsigned char buffer[READ_SIZE] = {0};
pclInitLibrary("Navigation", shutdownReg);
/**
* Logical DB ID: 0xFF with user 1 and seat 1
*
==> local value accessible by all users (user 1, seat 1)
*/
ret = pclKeyReadData(0xFF, "pos/last_position", 1, 1, buffer, READ_SIZE);
memset(buffer, 0, READ_SIZE);
/**
* Logical DB ID: 0xFF with user 0 and seat 0
*
==> local value accessible by all users (user 1, seat 1)
*/
ret = pclKeyReadData(0xFF, "language/country_code", 1, 1, buffer, READ_SIZE);
/**
* Logical DB ID: 0x84 with user 2 and seat 1
*
==> shared user value accessible by A GROUP (user 2 and seat 1)
*
*
==> used for shared testing
*/
ret = pclKeyWriteData(0x84, "links/last_link2", 2, 1, (unsigned char*)"Test notify
shared data", strlen("Test notify shared data"));
pclDeinitLibrary();
44
9.
Persistence Client Library Roadmap
This chapter shows the roadmap of the persistence client library development.
The interfaces described here are not yet part of the GENIVI compliance, but will later be
included into it later on.
The following API describes the version 1.6.0.0 of the plugin functions.
9.1.
Plugin interface
In order to extend the existing Persistence Client Library with custom storage solutions like
an own storage backend or data encryption, a plugin interface has been defined.
The plugin (shared object) will be loaded according the information in the configuration file,
either it will be loaded when the function pclInitLibrary will be called or when a plugin
function will be called the first time. The loading behavior is configured in the configuration
file.
The configuration file about the available plugins is expected in the following default folder
with the name "/etc/pclCustomLibConfigFile.cfg".
The default location and filename can be changed using the environment variable
"PERS_CLIENT_LIB_CUSTOM_LOAD".
For each key-value resource a different custom storage solution can be applied using the
Persistence Resource Configuration Table (RCT). The attribute storage type needs to be set
to "custom" and the name of the plugin shared object needs to be added to the attribute
custom name.
Only the key-value interface can be extended via the plugin interface, the file interface can't
be extended.
45
9.1.1.
Plugin types
There are predefined custom plugin types available:
•
•
•
•
•
•
•
9.1.2.
early
secure
emergency
hwinfo
custom1
custom2
custom3
plugin for loading early data
plugin to implement encrypting
plugin for emergency
plugin to query hardware information
used to implement something different then the predefines
Loading type
When will the plugin be loaded?
• init
plugin will be loaded when the pclInitLibrary function will be called
• od
on demand loading, the plugin will be loaded when a function of the
plugin will be called the first time.
9.1.3.
Initialization type
Specify the init function which will be called.
• sync
use the synchronous init type
• async
use the asynchronous init type
9.1.4.
Plugin configuration file format
The format of the plugin configuration file is the following:
<predefined type><blank><path to plugin><blank><loading type><blank><init type>
Example:
hwinfo /usr/local/lib/libhwinfoperscustom.so init async
secure /lib/libsecureperscustom.so od async
custom3 /usr/local/lib/libcustom3perscustom.so od sync
emergency /usr/local/lib/libemergencyperscustom.so init sync
46
9.2.
Function Overview
•
int plugin_init ()
initialize plugin (blocking)
•
int plugin_init_async (plugin_callback_async_t pfInitCompletedCB)
initialize plugin (non blocking)
•
int plugin_deinit ()
deinitialize plugin (during shutdown)
•
int plugin_delete_data (const char *path)
delete data
•
int plugin_get_size (const char *path)
gets the size of persistent data in bytes
•
int plugin_get_data (const char *path, char *buffer, int size)
get data
•
int plugin_handle_close (int handle)
close the given handle
•
int plugin_handle_get_data (int handle, char *buffer, int size)
get data
•
int plugin_handle_open (const char *path, int flag, int mode)
open a resource
•
int plugin_handle_set_data (int handle, char *buffer, int size)
set data
•
int plugin_create_backup (const char *backup_id)
create backup of the container's data
•
int plugin_get_backup (char *backup_id, int size)
get backup name
•
int plugin_restore_backup (const char *backup_id)
restore backup
•
int plugin_clear_all_data (void)
clear data (delete values for all the resources)
•
int plugin_set_data (const char *path, char *buffer, int size)
set data
•
int plugin_get_status_notification_clbk (plugin_callback_t pFunct)
registercallback for status notifications
•
int plugin_handle_get_size (int handle)
get size
•
int plugin_sync (void)
flush the cache (if used) into the non-volatile storage
•
int plugin_get_info (plugin_info_s *pInfo_out)
get the status information for the plugin's data
47
9.3.
Typedef Documentation
9.3.1.
typedef int(* plugin_callback_async_t)(int errcode)
typdef of callback function prototype for asynchronous init/deinit
Parameters:
errcode
9.3.2.
- pass PCCL_SUCCESS or an error code
(persistence_client_custom Return Values)
typedef int(* plugin_callback_t)(int, void *)
typdef of callback function prototype
Parameters:
int
void*
9.3.3.
pass a statusId to the function
pass an argument to the function
typedef struct _plugin_info_s plugin_info_s
information to be provided as status
48
9.4.
Function Documentation
9.4.1.
int plugin_clear_all_data (void )
clear data (delete values for all the resources)
Returns:
positive value: success; negative value: error code (persistence_client_custom Return Values)
Note:
•
•
9.4.2.
the new (empty) data content is flushed to non-volatile storage
To be used only by Persistence Administrator Service !
int plugin_create_backup (const char * backup_id)
create backup of the container's data
Parameters:
backup_id
backup destination's pathname (e.g. /tmp/bkup/mybackup.bk)
Returns:
positive value: backup success (size of backup, bytes); negative value: error code
Note:
•
•
•
•
The path (e.g. /tmp/bkup/ for our example) has to exist and to be accessible
The format of backup file is in responsibility of the customer plugin
The backup shall be created using the data in persistent storage (obtained after last
plugin_sync)
49
9.4.3.
int plugin_deinit ()
deinitialize plugin (during shutdown)
Returns:
positive value: deinit success; negative value: error code (persistence_client_custom Return
Values)
Note:
•
•
9.4.4.
This is the last function to call from this interface
The call is blocking.
int plugin_delete_data (const char * path)
delete data
Parameters:
path
the path to the data to delete
Returns:
positive value: delete success; negative value: error code (persistence_client_custom Return
Values)
9.4.5.
int plugin_get_backup (char * backup_id, int size)
get backup name
Parameters:
backup_id
size
Name of the backup / identifier
size of the buffer to return the identifier
Returns:
positive value: success, length of identifier; negative value: error code
50
9.4.6.
int plugin_get_data (const char * path, char * buffer, int size)
get data
Parameters:
path
buffer
size
the path to the resource to get
the buffer to store data
the number of bytes to get data
Returns:
positive value: size data read in bytes; negative value: error code (persistence_client_custom
Return Values)
9.4.7.
int plugin_get_info (plugin_info_s * pInfo_out)
get the status information for the plugin's data
Parameters:
pInfo_out
the status information
Returns:
positive value for success; negative value: error code (persistence_client_custom Return
Values)
Note:
•
9.4.8.
int plugin_get_size (const char * path)
gets the size of persistent data in bytes
Parameters:
path
the path to the data
Returns:
positive value: the size; negative value: error code (persistence_client_custom Return Values)
51
9.4.9.
int plugin_get_status_notification_clbk (plugin_callback_t pFunct)
registercallback for status notifications
Parameters:
pFunct
the callback
Returns:
positive value: register success; negative value error code (persistence_client_custom Return
Values)
9.4.10. int plugin_handle_close (int handle)
close the given handle
Parameters:
handle
the handle to close
Returns:
positive value: successfully closed; negative value: error code (persistence_client_custom
Return Values)
9.4.11. int plugin_handle_get_data (int handle, char * buffer, int size)
get data
Parameters:
handle
buffer
size
the handle returned from open
the buffer to store data
the number of bytes to get data
Returns:
positive value: size data read in bytes; negative value: error code (persistence_client_custom
Return Values)
52
9.4.12. int plugin_handle_get_size (int handle)
get size
Parameters:
handle
the handle given by open
Returns:
positive value: the size; negative value: error error code (persistence_client_custom Return
Values)
9.4.13. int plugin_handle_open (const char * path, int flag, int mode)
open a resource
Parameters:
path
flag
mode
the path to the resource to open
open flags
the open mode
Returns:
positive value: handle; negative value: error code (persistence_client_custom Return Values)
9.4.14. int plugin_handle_set_data (int handle, char * buffer, int size)
set data
Parameters:
handle
buffer
size
the handle given by open
the data to write
the number of bytes to write
Returns:
positive size data set; negative value: error code (persistence_client_custom Return Values)
53
9.4.15. int plugin_init ()
initialize plugin (blocking)
Returns:
positive value: init success; negative value: error code (persistence_client_custom Return
Values)
Note:
•
•
This (or plugin_init_async) is the first function to call from this interface
The call is blocking
9.4.16. int plugin_init_async (plugin_callback_async_t pfInitCompletedCB)
initialize plugin (non blocking)
Parameters:
pfInitComplet
edCB
the callback to be called when the initialization is complete
Returns:
positive value: init success; negative value: error code (persistence_client_custom Return
Values)
Note:
•
•
•
This (or plugin_init) is the first function to call from this interface
The call returns immediatelly.
Later, pfInitCompletedCB will be called when the initialization is complete.
9.4.17. int plugin_restore_backup (const char * backup_id)
restore backup
Parameters:
backup_id
backup source's pathname (e.g. /tmp/bkup/mybackup.bk)
Returns:
positive value: backup success (size of backup, bytes); negative value: error code
Note:
•
•
•
The source has to be compatible (i.e. obtained with plugin_create_backup)
The backup's data has first to be stored persistent and then reloaded in cache (if used)
54
9.4.18. int plugin_set_data (const char * path, char * buffer, int size)
set data
Parameters:
path
buffer
size
the path to the resource to set
the data to write
the number of bytes to write
Returns:
positive size data set; negative value: error code (persistence_client_custom Return Values)
9.4.19. int plugin_sync (void )
flush the cache (if used) into the non-volatile storage
Returns:
positive value for success; negative value: error code (persistence_client_custom Return
Values)
Note:
•
55
9.5.
Administration functions
9.5.1.
Defines
/// Client registered for fast lifecycle shutdown
#define PCL_SHUTDOWN_TYPE_FAST
2
/// Client registered for normal lifecycle shutdown
#define PCL_SHUTDOWN_TYPE_NORMAL 1
/// Client does not register to lifecycle shutdown
#define PCL_SHUTDOWN_TYPE_NONE
0
9.5.2.
pclInitLibrary
The pclInitLibrary initalizes the persistence client library
Syntax
int pclInitLibrary
(
const char* appname,
int shutdownMode
);
Parameters
appname
application name, the name must be a unique name in the system
shutdownMode
shutdown mode PCL_SHUTDOWN_TYPE_FAST or
PCL_SHUTDOWN_TYPE_NORMAL
Return Value
A positive value on success. When an error occurred a negative value will be returned with
th follwoing error codes: EPERS_LOCKFS, EPERS_NOT_INITIALIZED,
EPERS_INIT_DBUS_MAINLOOP, EPERS_REGISTER_LIFECYCLE,
EPERS_REGISTER_ADMIN
Remarks
This function will be called by the process using the PCL during startup phase.
56
9.5.3.
pclDeinitLibrary
The pclDeinitLibrary uninitializes the persistence client library
Syntax
int pclDeinitLibrary
(
void
);
Parameters
None.
Return Value
A positive value on success. On error a negative value will be returned.
Remarks
This function will be called during the shutdown phase of the process which uses the PCL.
57
9.6.
File API functions
9.6.1.
pclFileCreatePath
The pclFileCreatPath function create a path and the file if it does not exists.
A third party application can store their data to this file and the PCL does backup and
recovery.
Syntax
int pclCreatePath
(
unsigned int ldbid,
char** path,
unsigned int* size
);
Parameters
ldbid
logical database ID
resource_id
the resource ID
user_no
System/node
seat_no
the seat number
char** path
the location to store the path
unsigned int* size
size of the created path
Return Value
positive value (0 or greater) on success, which must be used when pclFileReleasePath will
be called. On error a negative value will be returned with th following error codes:
EPERS_LOCKFS or EPERS_COMMON
Remarks
This function will only be used by third party or legacy applications.
58
9.6.2.
pclFileReleasePath
The pclDeinitLibrary uninitializes the persistence client library
Syntax
int pclDeinitLibrary
(
int pathHandle
);
Parameters
pathHandle
path handle, returned by pclFileCreatePath
Return Value
positive value (0 or greater): success; On error a negative value will be returned with th
following error codes: EPERS_LOCKFS or EPERS_COMMON
Remarks
This function will only be used by third party or legacy applications.
59
10.
Best practice
10.1. The resource configuration table customID
The customID member of the resource configuration table (RCT) could be used to speed
up access time to resources within a custom storage extension plugin.
If a hash table or array will be used to store data in the custom extension plugin, the
customID can be used to generate the hash value into the hash table or the index into the
array offline and store this in the RCT for this resource.
If a customID is available the PCL generates a string using the lbid and the customID
which then will be used as path parameter for the custom plugin interface functions.
This may speed up access time as there is no need to generate the hash value or the index
during runtime, but the hash table and the array must be static and can't be changed during
runtime.
10.2. The pclInitLibrary function and shutdown mode
If a component does not need to receive lifecycle events, especially the shutdown events,
use the PCL_SHUTDOWN_TYPE_NONE define for the shutdownMode parameter.
An application can decide not to receive shutdown events when persistent data will only be
read and not written.
10.3. Shared data
If there is shared data, there is only one master application that writes (changes) this data
and only one or more applications that read this data.
If an application wants to be informed about shared data changes, use the
pclKeyRegisterNotifyOnChange function to register to change notifications.
10.4. User and seat identifier in the API
The PCL has the possibility to store data also per user and seat. If your system does not
have to possibility to provide user and seat information, just use a static seat- and user-ID in
the API.
Please use any number different form 0 as userID, because this is reserved to identify
system/node data.
60
10.5. Backup Location
The backup files is located in the folder "/Data/mnt-backup/" corresponding to the path given
from the original location within "/Data/mnt-wt/" or "/Data/mnt-c".
It is recommended to create a separate partition for the backup data, which will be mounted
to "/Data/mnt-backup/".
In order to guarantee the highest level of safety according to wear out issues and data
corruption, it is recommended to use a dedicated memory device only for the backup data.
Note:
This second memory device concept will most likely not be realized in a project due to
additional hardware cost.
61
11.
Persistence Usability Rules
GENIVI proposed 3 level rules about the usability of the Persistence Client Library.
11.1. Complete usage of the PCL (pclFileOpen .. pclFileClose)
Only file API functions provided by the PCL will be used to access persistent data, except
pclFileCreatePath and pclFileReleasePath functions.
Backup creation and recovery is within the responsibility of the PCL.
11.2. Usage of the PCL with pclFileCreatePath / pclFileReleasePath
Only the two API functions will be used to access persistent data.
The function pclFileCreatPath will be used to get a path to a file where the persistent
data will be stored.
The application can access the file in every way the application wants. Either the application
can use POSIX file access functions if the data will be written directly to a file or use SQL
functions to open and access a database file.
Backup creation and recovery is within the responsibility of the PCL.
11.3. Free access persistence data
An application has free access to the specific structure defined in the persistence concept. It
is allowed to directly access the persistence file/folder structure in the way the application
wants. The complete management of backup and recovery is in responsibility of the
application.
62
12.
Appendix
Appendix A: Related Documents ................................................................................................. 64
Appendix B: Abbreviations ........................................................................................................... 64
Appendix C: Glossary .................................................................................................................... 65
63
Appendix A: Related Documents
Document
Persistence Architecture
Documentation
Reference
http://docs.projects.genivi.org/persistence-clientlibrary/1.0/GENIVI_Persistence_ArchitectureDocumentation.pdf
Appendix B: Abbreviations
Abbreviation
API
DLT
eMMC
GENIVI
IPC
ldbid
Linux VFS
NAND
NOR
NSM
PAS
RCT
PCL
SSD
PCL
PoC
PCO
Description
Application Programming Interface
Diagnostic Log and Trace
embedded Multimedia Card
The GENIVI Alliance is a non-profit consortium whose goal is to
establish a globally competitive, Linux-based operating system,
middleware and platform for the automotive in-vehicle infotainment
(IVI) industry.
Inter-Process Communication
Logical Database Identifier
Linux Virtual File System (Abstraction layer on top of a more concrete
file system)
flash memory, a type of non-volatile computer memory
NOR Flash Memory, a type of non-volatile computer memory
Node State Manager (GENIVI lifecycle Component)
Persistence Administration Service
Resource Configuration Table
Solid-state drive
Proof of Concept
Persistence Common Object
http://git.projects.genivi.org/?p=persistence/persistence-commonobject.git;a=summary
64
Appendix C: Glossary
Abbreviation
Wear-out
Description
Most flash devices are guaranteed to
withstand around 100,000
program/erase cycles before the wear
begins to deteriorate the integrity of the
storage.
65

User Manual Persistence Client Library Description

Transcription

Similar documents

Sample Midterm CSE 680: Introduction to Algorithms and Data Structures

ICSE Computer Application Sample Papers SECTION A (40 Marks)

IE 201 – Sample Midterm Questions

Gataka: A banking trojan ready to take off?

How to build, deploy and test SCOS 2000 www.visionspace.com April 30, 2014

Computer Science - Class - XII Sample Paper - 3

Programación orientada a objetos

CSC 171 Sample Quiz 6 C Language Programming for Engineers

Rekall Memory Forensics