Library Interface

Signal Interface

One or more signals are specified to the gscope library as an array of GscopeSignal structures. A GscopeSignal structure is defined in gscope_interface.h as follows:

    typedef struct {
            char *title;
            GscopeUserData signal;
            gchar *color;
            gfloat min;
            gfloat max;
            GscopeSignalLine line;
            gboolean hidden;
            gfloat filter;
    } GscopeSignal;
      

The title and color fields are the name and the color of the signal. The min and max fields are used for display. For default values of the zoom and bias factors (see the section called Zoom and Bias Factors), the minimum value of the signal is shown on the bottom of the scope and the maximum value of the signal is shown on the top of the scope. The line field is used to specify the line mode in which the signal is drawn (see Line Mode in the section called The Menubar). The hidden field specifies whether the signal is hidden or visible by default. The filter is a parameter of a low-pass filter on the signal. By default, its value is zero and the signal is not filtered. The filter value ranges from zero to one. The signal field is used to obtain signal data and is described below with an example.

    /* Example 1 */
    int decoder;
    GscopeSignal decoder_sig = {"Decoder", {INTEGER, &decoder}, "aquamarine", -100.0,
                                100.0};
    /* Example 2 */
    float mtu;
    GscopeSignal mtu_sig = {"MTU", {FLOAT, &mtu}, "orange", 10.0, 99.0,
                            LINE_SIGNAL};
    /* Example 3 */
    static void get_set_audio(gscope_rw_flag rw, void *arg1, void *arg2, 
                              float *value);
    /* type check the function. GSCOPE_RW_FUNC is explained below */
    static GSCOPE_RW_FUNC dummy = get_set_audio;
    GscopeSignal audio_sig = {"Audio",   {FUNC, get_set_audio, 0, 0}, "springgreen3",
                              0.0, 99.0, LINE_SIGNAL, TRUE}; 
  
      

Example 1 shows how three signals are defined in gscope_test for the Processes scope. The signal field is of type GscopeUserData which is defined in gscope_interface.h as follows:

    typedef enum {
            INTEGER, SHORT, FLOAT, FUNC, NONE
    } GscopeUserDataType;
    
    typedef struct {
            GscopeUserDataType type;
            void *obj;
            void *arg1;
            void *arg2;
    } GscopeUserData;
      

The type field is of type GscopeUserDataType. The obj field is a pointer to an integer, short, float or a function. Signal data is read from this pointer using the type information. The arg1 and arg2 fields are optional and only used when obj is of type FUNC. When obj is a function, its type is GSCOPE_RW_FUNC which is defined as follows:

    typedef enum {
            GSCOPE_READ_DATA, GSCOPE_WRITE_DATA
    } gscope_rw_flag;
    typedef void (*GSCOPE_RW_FUNC) (gscope_rw_flag read_write_flag, 
                                    void *arg1, void *arg2, float *value);
      

The function should be written so that when the first parameter of the function is GSCOPE_READ_DATA, data is read and passed out from this function into the value parameter. When the first parameter is GSCOPE_WRITE_DATA, data is written and passed into the function via the value parameter. The arg1 and arg2 parameters are passed to the function from the GscopeUserData structure. The function mechanism allows reading and writing arbitrary signal data.

Parameter Interface

One or more application parameters is specified to the gscope library as an array of GscopeParameter structures. A GscopeParameter structure is defined in gscope_interface.h as follows:

    /* User specified parameter data */
    typedef struct {
            char *title;
            GscopeUserData parameter;
            gfloat lower;   /* The lower and upper values 
                               are not enforced when lower == upper */
            gfloat upper;
    } GscopeParameter;
      

The title field is the name of the parameter. The lower and upper fields are used to ensure that the parameter does not exceed its range. When these fields are the same, this enforcement is not done. The parameter is of type GscopeUserData and can be read or written just as signal data (see the section called Signal Interface). Note that while signal data is only read, parameters are both read from the application and can be written or modified using the Preferences menu (see Preferences in the section called The Menubar).

Parameters can be nested in the Preferences menu. Parameters are nested by placing slashes ("/") in the title. For instance, a parameter title of "ProcessId/status" will place "status" within a "ProcessId" tree. Nesting can be used to group large numbers of parameters for easier display.

Recording File Format

The file format for recording data when the scope is in polling mode or for playing data in playback mode is the same. It consists of 3 columns where the first column is the time axis (or the x-axis), the second column is the y-axis and the third column is the signal name. This format allows several signals to be recorded in the same file. As a special case, if there is only one signal, then the third column does not have to exist. In that case, file data consists of tuples of data.

The first column should be sorted in increasing time order and its value should be in milliseconds. Data is plotted from the file one pixel apart for each sampling period (when the X zoom factor is set to 1). For instance, if the sampling period is 50 ms, then consecutive data points in the file that are 100 ms apart will be plotted 2 pixels apart.