Data logging internals

Session structures, limits and wire format shared by the data logging service. More...

Data Structures
struct	DataLoggingSessionStorage
	Location of a session's data in its file. More...
struct	DataLoggingSessionComm
	Endpoint state of a session. More...
struct	DataLoggingActiveState
	State of an active session. More...
struct	DataLoggingSession
	Data logging session. More...
struct	DataLoggingSendDataMessage
	Data message, sent with DataLoggingEndpointCmdData. More...

Macros
#define	DLS_FILE_NAME_PREFIX   "dls_storage_"
	Prefix of session file names, followed by the decimal session ID.
#define	DLS_MAX_DATA_BYTES    (DLS_TOTAL_STORAGE_BYTES - (DLS_MAX_NUM_SESSIONS * DLS_FILE_INIT_SIZE_BYTES))
	Space available to session files beyond their initial size.
#define	DLS_INVALID_FILE   (-1)
	Value of DataLoggingSessionStorage::fd when the session has no open file.
#define	DLS_SESSION_MAX_BUFFERED_ITEM_SIZE   300U
	Largest item size, and largest dls_log() write, for buffered sessions.
#define	DLS_SESSION_MIN_BUFFER_SIZE   (DLS_SESSION_MAX_BUFFERED_ITEM_SIZE + 1)
	Size of a buffered session's buffer.

Enumerations
enum	DataLoggingStatus { DataLoggingStatusActive = 0x01 , DataLoggingStatusInactive = 0x02 }
	Session status. More...
enum	DataLoggingEndpointCmd {   DataLoggingEndpointCmdOpen = 0x01 , DataLoggingEndpointCmdData = 0x02 , DataLoggingEndpointCmdClose = 0x03 , DataLoggingEndpointCmdReport = 0x04 ,   DataLoggingEndpointCmdAck = 0x05 , DataLoggingEndpointCmdNack = 0x06 , DataLoggingEndpointCmdTimeout = 0x07 , DataLoggingEndpointCmdEmptySession = 0x08 ,   DataLoggingEndpointCmdGetSendEnableReq = 0x09 , DataLoggingEndpointCmdGetSendEnableRsp = 0x0A , DataLoggingEndpointCmdSetSendEnable = 0x0B }
	Data logging endpoint commands. More...
enum	DataLoggingSessionCommState { DataLoggingSessionCommStateOpening , DataLoggingSessionCommStateIdle , DataLoggingSessionCommStateSending }
	Endpoint state of a session. More...

Functions
bool	dls_private_send_session (DataLoggingSession *logging_session, bool empty)
	Send the next chunk of a session's stored data to the phone.
void	dls_private_handle_disconnect (void *data)
	Reset the endpoint state of all sessions after a disconnection.
int	dls_test_read (DataLoggingSession *logging_session, uint8_t *buffer, int num_bytes)
	Read session data, for unit tests only.
int	dls_test_consume (DataLoggingSession *logging_session, int num_bytes)
	Consume session data, for unit tests only.
int	dls_test_get_num_bytes (DataLoggingSession *logging_session)
	Get the number of unread bytes, for unit tests only.
int	dls_test_get_tag (DataLoggingSession *logging_session)
	Get the session tag, for unit tests only.
uint8_t	dls_test_get_session_id (DataLoggingSession *logging_session)
	Get the session ID, for unit tests only.

Variables
static const uint32_t	DLS_FILE_NAME_MAX_LEN = 20
	Size of a buffer holding a session file name.
static const uint32_t	DLS_FILE_INIT_SIZE_BYTES = PBL_KIB(4)
	Initial size of a session file.
static const uint32_t	DLS_MIN_FILE_FREE_BYTES = PBL_KIB(8)
	Minimum free space added when a session file grows.
static const uint32_t	DLS_MAX_FILE_FREE_BYTES = PBL_KIB(100)
	Maximum free space added when a session file grows.
static const uint32_t	DLS_MIN_FREE_BYTES = PBL_KIB(1)
	Free space left at the end of a session file below which the file is grown.
static const uint32_t	DLS_MAX_NUM_SESSIONS = 20
	Maximum number of sessions.
static const uint32_t	DLS_TOTAL_STORAGE_BYTES = PBL_KIB(640)
	Maximum file system space used by all session files.
static const uint8_t	DLS_ENDPOINT_CMD_MASK = 0x7f
	Mask of the command in the first byte of an endpoint message.
static const uint32_t	DLS_ENDPOINT_MAX_PAYLOAD
	Largest data message payload, and largest item size for unbuffered sessions.

Detailed Description

Session structures, limits and wire format shared by the data logging service.

---

Data Structure Documentation

DataLoggingSessionStorage

struct DataLoggingSessionStorage

Location of a session's data in its file.

Data Fields
int	fd	PFS file descriptor, or DLS_INVALID_FILE when not open.
uint32_t	num_bytes	Number of unread bytes.
uint32_t	read_offset	File offset of the next read.
uint32_t	write_offset	File offset of the next write.

DataLoggingSessionComm

struct DataLoggingSessionComm

Endpoint state of a session.

Data Fields
RtcTicks	ack_timeout	Time in RTC ticks at which the pending ack times out, 0 when not waiting for one.
uint8_t	nack_count	Number of times the phone nacked this session.
int	num_bytes_pending	Bytes sent to the phone and not acked yet.
uint8_t	session_id	Session ID, chosen by the watch and unique among its sessions.
DataLoggingSessionCommState	state: 8	Endpoint state.

DataLoggingActiveState

struct DataLoggingActiveState

State of an active session.

Data Fields
struct pbl_shared_cbuf	buffer	Circular buffer of a buffered session.
struct pbl_shared_cbuf_client	buffer_client	Reader of buffer, consumed by KernelBG.
bool	buffer_in_kernel_heap: 1	buffer_storage is on the kernel heap, else on the heap of the dls_create() caller.
uint8_t *	buffer_storage	Storage of buffer, NULL for unbuffered sessions.
bool	inactivate_pending: 1	Inactivate the session once its last lock is released, see dls_unlock_session().
struct pbl_mutex	mutex	Session lock, see dls_lock_session().
uint8_t	open_count	Number of locks held, changed under the list mutex. The state is freed only at 0.
bool	write_request_pending: 1	A flash write has been requested from KernelBG and not run yet.

DataLoggingSession

struct DataLoggingSession

Data logging session.

Data logging session handle.

Data Fields
Uuid	app_uuid	Owner UUID.
DataLoggingSessionComm	comm	Endpoint state.
DataLoggingActiveState *	data	Active state, NULL for inactive sessions.
uint16_t	item_size	Item size in bytes.
DataLoggingItemType	item_type: 4	Item type.
struct DataLoggingSession *	next	Next session in the list.
time_t	session_created_timestamp	Creation time.
DataLoggingStatus	status: 4	Session status.
DataLoggingSessionStorage	storage	Flash storage state.
uint32_t	tag	Session tag.
PebbleTask	task	Task that created the session.

DataLoggingSendDataMessage

struct DataLoggingSendDataMessage

Data message, sent with DataLoggingEndpointCmdData.

Data Fields
uint8_t	bytes[]	Whole items.
uint8_t	command	DataLoggingEndpointCmdData.
uint32_t	crc32	Legacy CRC-32 of bytes.
uint32_t	items_left_hereafter	Items left after this message; currently always 0xffff.
uint8_t	session_id	Session ID.

Macro Definition Documentation

DLS_FILE_NAME_PREFIX

#define DLS_FILE_NAME_PREFIX   "dls_storage_"

Prefix of session file names, followed by the decimal session ID.

DLS_INVALID_FILE

#define DLS_INVALID_FILE   (-1)

Value of DataLoggingSessionStorage::fd when the session has no open file.

DLS_MAX_DATA_BYTES

#define DLS_MAX_DATA_BYTES    (DLS_TOTAL_STORAGE_BYTES - (DLS_MAX_NUM_SESSIONS * DLS_FILE_INIT_SIZE_BYTES))

Space available to session files beyond their initial size.

DLS_SESSION_MAX_BUFFERED_ITEM_SIZE

#define DLS_SESSION_MAX_BUFFERED_ITEM_SIZE   300U

Largest item size, and largest dls_log() write, for buffered sessions.

DLS_SESSION_MIN_BUFFER_SIZE

#define DLS_SESSION_MIN_BUFFER_SIZE   (DLS_SESSION_MAX_BUFFERED_ITEM_SIZE + 1)

Size of a buffered session's buffer.

One byte more than DLS_SESSION_MAX_BUFFERED_ITEM_SIZE, as needed by the circular buffer.

Enumeration Type Documentation

DataLoggingEndpointCmd

enum DataLoggingEndpointCmd

Data logging endpoint commands.

Enumerator
DataLoggingEndpointCmdOpen	Watch opens a session.
DataLoggingEndpointCmdData	Watch sends session data, see DataLoggingSendDataMessage.
DataLoggingEndpointCmdClose	Watch closes a session.
DataLoggingEndpointCmdReport	Phone reports the sessions it knows about.
DataLoggingEndpointCmdAck	Phone acknowledges an open or data message.
DataLoggingEndpointCmdNack	Phone rejects an open or data message.
DataLoggingEndpointCmdTimeout	Watch reports that an ack was not received in time.
DataLoggingEndpointCmdEmptySession	Phone asks to send a session's data now.
DataLoggingEndpointCmdGetSendEnableReq	Phone asks whether sending is enabled.
DataLoggingEndpointCmdGetSendEnableRsp	Watch answers DataLoggingEndpointCmdGetSendEnableReq.
DataLoggingEndpointCmdSetSendEnable	Phone enables or disables sending.

DataLoggingSessionCommState

enum DataLoggingSessionCommState

Endpoint state of a session.

 +----------+  Rx Ack    +----------+    Tx Data   +----------+
 | Opening  |----------->| Idle     |+------------>| Sending  |
 +----------+            +----------+              +----------+
                              ^                         |
                              |       Rx Ack            |
                              +-------------------------+

Enumerator
DataLoggingSessionCommStateOpening	Waiting for the phone to ack the open message.
DataLoggingSessionCommStateIdle	Ready to send data.
DataLoggingSessionCommStateSending	Waiting for the phone to ack sent data.

DataLoggingStatus

enum DataLoggingStatus

Session status.

Enumerator
DataLoggingStatusActive	Created and still being logged to.
DataLoggingStatusInactive	Closed by its owner, or its owner exited; remaining data is still sent to the phone.

Function Documentation

dls_private_handle_disconnect()

void dls_private_handle_disconnect

(

void *

data

)

Reset the endpoint state of all sessions after a disconnection.

Must be called from KernelBG.

Parameters

data

Unused.

dls_private_send_session()

bool dls_private_send_session	(	DataLoggingSession *	logging_session,
		bool	empty
	)

Send the next chunk of a session's stored data to the phone.

Must be called from KernelBG. Removes inactive sessions with no data left. Active sessions are only sent when they hold enough data, unless empty is set.

Parameters

logging_session	Session.
empty	Send even if little data is stored.

Returns

false on unexpected errors, true otherwise (including when nothing was sent).

dls_test_consume()

int dls_test_consume	(	DataLoggingSession *	logging_session,
		int	num_bytes
	)

Consume session data, for unit tests only.

Parameters

logging_session	Session.
num_bytes	Number of bytes to consume.

Returns

num_bytes.

dls_test_get_num_bytes()

int dls_test_get_num_bytes

(

DataLoggingSession *

logging_session

)

Get the number of unread bytes, for unit tests only.

Parameters

logging_session

Session.

Returns

Unread bytes.

dls_test_get_session_id()

uint8_t dls_test_get_session_id

(

DataLoggingSession *

logging_session

)

Get the session ID, for unit tests only.

Parameters

logging_session

Session.

Returns

Session ID.

dls_test_get_tag()

int dls_test_get_tag

(

DataLoggingSession *

logging_session

)

Get the session tag, for unit tests only.

Parameters

logging_session

Session.

Returns

Session tag.

dls_test_read()

int dls_test_read	(	DataLoggingSession *	logging_session,
		uint8_t *	buffer,
		int	num_bytes
	)

Read session data, for unit tests only.

Parameters

	logging_session	Session.
[out]	buffer	Destination.
	num_bytes	Maximum number of bytes to read.

Returns

See dls_storage_read().

Variable Documentation

DLS_ENDPOINT_CMD_MASK

const uint8_t DLS_ENDPOINT_CMD_MASK = 0x7f

static

Mask of the command in the first byte of an endpoint message.

The top bit is set in commands from the phone and clear in commands from the watch.

DLS_ENDPOINT_MAX_PAYLOAD

const uint32_t DLS_ENDPOINT_MAX_PAYLOAD

static

Initial value:

=
    (COMM_MAX_OUTBOUND_PAYLOAD_SIZE - sizeof(DataLoggingSendDataMessage))

Largest data message payload, and largest item size for unbuffered sessions.

DLS_FILE_INIT_SIZE_BYTES

const uint32_t DLS_FILE_INIT_SIZE_BYTES = PBL_KIB(4)

static

Initial size of a session file.

DLS_FILE_NAME_MAX_LEN

const uint32_t DLS_FILE_NAME_MAX_LEN = 20

static

Size of a buffer holding a session file name.

DLS_MAX_FILE_FREE_BYTES

const uint32_t DLS_MAX_FILE_FREE_BYTES = PBL_KIB(100)

static

Maximum free space added when a session file grows.

DLS_MAX_NUM_SESSIONS

const uint32_t DLS_MAX_NUM_SESSIONS = 20

static

Maximum number of sessions.

DLS_MIN_FILE_FREE_BYTES

const uint32_t DLS_MIN_FILE_FREE_BYTES = PBL_KIB(8)

static

Minimum free space added when a session file grows.

A file grows by half its unread data, clamped to this and DLS_MAX_FILE_FREE_BYTES.

DLS_MIN_FREE_BYTES

const uint32_t DLS_MIN_FREE_BYTES = PBL_KIB(1)

static

Free space left at the end of a session file below which the file is grown.

DLS_TOTAL_STORAGE_BYTES

const uint32_t DLS_TOTAL_STORAGE_BYTES = PBL_KIB(640)

static

Maximum file system space used by all session files.