From f5464725ea2c2344ffa73a67eac22b9f0ddb65dd Mon Sep 17 00:00:00 2001 From: Julien Desfossez Date: Thu, 13 Sep 2012 18:47:34 -0400 Subject: [PATCH 1/1] Fix: Documentation cleanup Add high-level information about declarations, definitions and scopes in the API documentation. Add some missing API function documentation in the API doc. Clarify the usage of the declaration listing functions. Signed-off-by: Julien Desfossez Signed-off-by: Mathieu Desnoyers --- doc/API.txt | 35 ++++++++++++++++++++++++++----- include/babeltrace/ctf/events.h | 25 +++++++++++++++------- include/babeltrace/trace-handle.h | 2 +- 3 files changed, 49 insertions(+), 13 deletions(-) diff --git a/doc/API.txt b/doc/API.txt index bc3a4a10..e13e6adf 100644 --- a/doc/API.txt +++ b/doc/API.txt @@ -28,6 +28,20 @@ TERMINOLOGY * A "trace handle" is a unique identifier representing a trace file. It allows the user to manipulate a trace directly. +* The "declaration" of a field or an event, is the structure which contains + the representaion of an object as declared in the metadata. All the + declarations of all events and fields can be accessed as soon as the trace is + open, but of course they contain no trace data, just the layout. + +* The "definition" of a field or an event is the structure in which the actual + trace data is contained. When we read an event in the trace, we access its + definition and we can access all the field definitions contained in all the + scopes of this event to the get the actual data. + +* "Scopes" allow specifying the level at which the information about the + current event must be fetched: event header, event payload, event context, + stream context. Compound-type (arrays, structures, sequences and variants) + fields are relative scopes which contain fields. USAGE @@ -125,8 +139,13 @@ variant) For more information on each scope, see the CTF specifications. -The function to get a field list is the bt_ctf_get_field_list(). The function -to get the definition of a specific field is bt_ctf_get_field(). +The bt_ctf_get_field_list() function gives access to the list of fields in the +current event. The bt_ctf_get_field() function gives acces to of a specific +field of an event. + +The bt_ctf_get_event_decl_list() and bt_ctf_get_decl_fields() functions give +respectively access to the list of the events declared in a trace and the list +of the fields declared in an event. Once the field is obtained, we can obtain its name and type using the bt_ctf_field_name() and bt_ctf_field_type() functions respectively. The @@ -143,8 +162,8 @@ possible types are defined in the ctf_type_id enum: CTF_TYPE_SEQUENCE, NR_CTF_TYPES. -Depending on the field type, we can get informations about the field with these -functions: +Depending on the field type, we can get informations about the field with the +following functions: * bt_ctf_get_index() return the element at the index position of an array of a sequence; @@ -166,7 +185,13 @@ functions: CTF_STRING_ASCII, CTF_STRING_UNKNOWN. -These functions give access to the value associated with a field : +All of these functions require a field declaration as parameter, depending on +the source type of data (struct definition* or struct bt_ctf_field_decl*), the +user might have to call bt_ctf_get_decl_from_def() or +bt_ctf_get_decl_from_field_decl(). + +The following functions give access to the value associated with a field +defintion: * bt_ctf_get_uint64(); * bt_ctf_get_int64(); * bt_ctf_get_char_array(); diff --git a/include/babeltrace/ctf/events.h b/include/babeltrace/ctf/events.h index 461cf06c..57e067e9 100644 --- a/include/babeltrace/ctf/events.h +++ b/include/babeltrace/ctf/events.h @@ -109,9 +109,9 @@ uint64_t bt_ctf_get_timestamp(const struct bt_ctf_event *event); /* * bt_ctf_get_field_list: obtain the list of fields for compound type * - * This function can be used to obtain the list of fields - * contained within a compound type: array, sequence, - * structure, or variant. + * This function can be used to obtain the list of fields contained + * within a top-level scope of an event or a compound type: array, + * sequence, structure, or variant. * This function sets the "list" pointer to an array of definition * pointers and set count to the number of elements in the array. @@ -232,10 +232,16 @@ char *bt_ctf_get_string(const struct definition *field); int bt_ctf_field_get_error(void); /* - * bt_ctf_get_event_decl_list: set list pointer to an array of bt_ctf_event_decl - * pointers and set count to the number of elements in the array. + * bt_ctf_get_event_decl_list: get a list of all the event declarations in + * a trace. + * + * The list array is pointed to the array of event declarations. + * The number of events in the array is written in count. * * Return 0 on success and a negative value on error. + * + * The content pointed to by "list" should *not* be freed. It stays + * valid as long as the trace is opened. */ int bt_ctf_get_event_decl_list(int handle_id, struct bt_context *ctx, struct bt_ctf_event_decl * const **list, @@ -247,10 +253,15 @@ int bt_ctf_get_event_decl_list(int handle_id, struct bt_context *ctx, const char *bt_ctf_get_decl_event_name(const struct bt_ctf_event_decl *event); /* - * bt_ctf_get_decl_fields: set list pointer to an array of bt_ctf_field_decl - * pointers and set count to the number of elements in the array. + * bt_ctf_get_decl_fields: get all field declarations in a scope of an event + * + * The list array is pointed to the array of field declaration. + * The number of field declaration in the array is written in count. * * Returns 0 on success and a negative value on error + * + * The content pointed to by "list" should *not* be freed. It stays + * valid as long as the trace is opened. */ int bt_ctf_get_decl_fields(struct bt_ctf_event_decl *event_decl, enum bt_ctf_scope scope, diff --git a/include/babeltrace/trace-handle.h b/include/babeltrace/trace-handle.h index 426800d8..f4c44065 100644 --- a/include/babeltrace/trace-handle.h +++ b/include/babeltrace/trace-handle.h @@ -54,7 +54,7 @@ uint64_t bt_trace_handle_get_timestamp_begin(struct bt_context *ctx, /* * bt_trace_handle_get_timestamp_end : returns the destruction timestamp - * (in anoseconds or cycles depending on type) of the buffers of a trace + * (in nanoseconds or cycles depending on type) of the buffers of a trace * or -1ULL on error. */ uint64_t bt_trace_handle_get_timestamp_end(struct bt_context *ctx, -- 2.34.1