Subversion Repositories shark

%----------------------------------------------------------------------------

\chapter{The Input Library}

%----------------------------------------------------------------------------

This library allow the user to interact with applications. Is composed by a

lower lever which must be initialized at the beginning. On top of this layer we

can find different peripherals:

\begin{itemize}

\item Keyboard;

\item Mouse;

\item Joystick;

\item Speaker;

\item Event debugger.

\end{itemize}

Each one can work independently from the others. In order to use the low lever

functions, the files \texttt{drivers/shark\_input26.h} must be included. It

contains the prototypes of the declared functions. First of all, the keyboard

needs be initialized by the calling \texttt{KEYB26\_init} primitive into the

\texttt{\_\_init\_\_} function in the initialization file or in any other point

of the application code.

\vspace{7mm}

\begin{intest}

INPUT26\_INIT\index{INPUT26\_init()}

\end{intest}

\begin{description}

\item [\textbf{int INPUT26\_init(void);}]

\item [\textbf{Description:}]It initializes the low lever input interface and

the library's internal data structures.

\item [\textbf{Return value:}] 0 if the operation is performed successfully; a

value less than 0, otherwise.

\end{description}

\vspace{7mm}

The following code shows an example of input drivers initialization for the

system:

\begin{description}

\item [Example:]

\end{description}

\begin{verbatim}

int res;

KEYB_PARMS kparms = BASE_KEYB;

MOUSE_PARMS mparms = BASE_MOUSE;

LINUXC26_register_module(TRUE);

INPUT26_init();

keyb_def_map(kparms, KEYMAP_IT);

keyb_def_ctrlC(kparms, NULL);

KEYB26_init(&kparms);

mouse_def_threshold(mparms, 5);

mouse_def_xmin(mparms, 0);

mouse_def_ymin(mparms, 0);

mouse_def_xmax(mparms, 639);

mouse_def_ymax(mparms, 479);

MOUSE26_init(&mparms);

SPEAK26_init();

JOY26_init();

...

\end{verbatim}

\vspace{7mm}

The event debugger is used to have an output of the raw data coming from an

input device for which a driver is not present. It can be stanter, stopper and

is possible to control the actual status.

\vspace{7mm}

\begin{intest}

EVBUG26\_INIT\index{EVBUG26\_init()}

\end{intest}

\begin{description}

\item [\textbf{int EVBUG26\_init(void);}]

\item [\textbf{Description:}]It initializes the event debugger interface and the

library's internal data structures.

\item [\textbf{Return value:}] 0 if the operation is performed successfully; a

value less than 0, otherwise.

\end{description}

\begin{intest}

EVBUG26\_CLOSE\index{EVBUG26\_close()}

\end{intest}

\begin{description}

\item [\texttt{int EVBUG26\_close(void);}]

\item [\textbf{Description:}]It close the event debugger interface.

\item [\textbf{Return value:}] 0 if the operation is performed successfully; -1

if the interface in not installed.

\end{description}

\begin{intest}

EVBUG26\_INSTALLED\index{EVBUG26\_installed()}

\end{intest}

\begin{description}

\item [\texttt{int EVBUG26\_installed(void);}]

\item [\textbf{Description:}]Return if the event debugger is actually installed.

\item [\textbf{Return value}:] 0 if the module is installed; 1 otherwise.

\end{description}

%----------------------------------------------------------------------------

\section{The keyboard library}

%----------------------------------------------------------------------------

In order to use the keyboard handling functions, the

\texttt{drivers/shark\_keyb26.h} header file, containing the interface

functions' prototypes, has to be included in the application program.

First of all, the keyboard needs be initialized by the calling

\texttt{KEYB26\_init} primitive into the \texttt{\_\_init\_\_} function in the

initialization file or in any other point of the application code and the input

low level driver must be already installed. A programmer can either initialize

the keyboard using the default settings or define his own parameters which are

encapsulated into a structure having \texttt{KEY\_PARMS} type. The strucuture

can be initialized with the default set of values by setting it equal to

\texttt{BASE\_KEYB}; the \texttt{keyb\_def\_...} macros can be used before

calling \texttt{KEYB26\_init} to modify each setting. Afterwards, it is possible

to read the ASCII code of any stroken key by calling the \texttt{keyb\_getch()}

function. This function requires a parameter which determines whether the task

should block until a key is hit or not. In the latter case, if no key has been

hit, the function returns 0 (behaving like \texttt{kbhit()}).

If we are interested in the key's scan code, we can call the

\texttt{keyb\_getcode()} function, which returns a struct containing either the

scan code or the ascii code and a byte containing information on the ALT, SHIFT

or CTRL key being pressed.

The following code shows an example of usage for the function:

\begin{verbatim}

KEY_EVT k;

...

if (keyb_getcode(&k, NON_BLOCK) {

   if (isRightCtrl(k) || isLeftCtrl(k)) && (k.ascii == 'x')) {

      /* Ctrl + `x' has been pressed */

      ...

   }

}

...

\end{verbatim}

\noindent Finally, it is possible to define a function to be automatically

called every time a specific key (or a specific combination of keys) is pressed.

This is done by calling the \texttt{keyb\_hook()} function, which receives as

arguments a data structure containing the required combination of keys and the

function to be called.

\vspace{7mm}

\begin{intest}

KEYB26\_INIT\index{KEYB26\_init()}

\end{intest}

\begin{description}

\item [\textbf{int KEYB26\_init(KEYB\_PARMS {*}parms);}]

\item [\textbf{Description:}]It initializes the keyboard interface and the

library's internal data structures. It can be called using NULL as

\texttt{parms} to initialize the keyboard interface to default values. \\ Note

that to be proper initialized, you need also to initialize the HARTPORT

modules.

\item [\textbf{Return value:}] 0 if the operation is performed successfully; a

value less than 0, otherwise.

\end{description}

\begin{intest}

KEYB26\_CLOSE\index{KEYB26\_close()}

\end{intest}

\begin{description}

\item [\textbf{int KEYB26\_close(void);}]

\item [\textbf{Description:}]It close the keyboard interface.

\item [\textbf{Return value:}] 0 if the operation is performed successfully; -1

if the keyboard in not installed.

\end{description}

\begin{intest}

KEYB26\_INSTALLED\index{KEYB26\_installed()}

\end{intest}

\begin{description}

\item [\texttt{int KEYB26\_installed(void);}]

\item [Description:]Return if the keyboard driver is actually installed.

\item [\textbf{Return value:}] 0 if the keyboard is installed; 1 otherwise.

\end{description}

\begin{intest}

KEYB\_DEFAULT\_PARM\index{keyb\_default\_parm()}

\end{intest}

\begin{description}

\item [\textbf{void keyb\_default\_parm(KEYB\_PARMS parms);}]

\item [\textbf{Description:}] It changes the values of parms to the same vales

as the BASE\_KEYB default initializer.

\end{description}

\begin{intest}

KEYB\_DEF\_MAP\index{keyb\_def\_map()}

\end{intest}

\begin{description}

\item [\textbf{void keyb\_def\_map(KEYB\_PARMS parms, unsigned char map);}]

\item [\textbf{Description:}]It changes the default map used for the keyboard:

\texttt{map} can be \texttt{KEYMAP\_US} for an english keyboard or

\texttt{KEYMAP\_IT} for an italian keyboard. The default is english keyboard

layout.

\end{description}

\begin{intest}

KEYB\_DEF\_CTRLC\index{keyb\_def\_ctrlC()}

\end{intest}

\begin{description}

\item [\textbf{void keyb\_def\_ctrlC(KEYB\_PARMS parms, void

({*}ctrlcfunc)(KEY\_EVT {*}k));}]

\item [\textbf{Description:}] It enables the execution of a function when the

{}``ctrl\-C'' combination is pressed. By default, if this macro is not used, the

\texttt{ctrl\-C} combination results in calling \texttt{sys\_end()}. Note that a

small message is printed also on the console. The message is only visible if the

system is in text mode. If you are running a graphic application, remember to

redefine the Ctrl-C Handler!

\end{description}

\begin{intest}

KEYB\_DEF\_TASK\index{keyb\_def\_task()}

\end{intest}

\begin{description}

\item [\textbf{void keyb\_def\_task(KEYB\_PARMS parms, TASK\_MODEL {*} m);}]

\item [\textbf{Description:}] It specifies the parameters of the keyboard

server. The \texttt{TASK\_MODEL} {*} should be a valid pointer to a Task Model,

or \texttt{KEYB\_DEFAULT} if you want to specify the default behaviour. \\

This macro should be used every time the default server Task Model does not

adapt well to the configuration of the scheduling modules registered in the

system. \\

The default server Task Model is equivalent to this initialization:\\

\texttt{soft\_task\_default\_model(base\_m);}\\

\texttt{soft\_task\_def\_wcet(base\_m,2000);}\\

\texttt{soft\_task\_def\_met(base\_m,800);}\\

\texttt{soft\_task\_def\_period(base\_m,25000);}\\

\texttt{soft\_task\_def\_system(base\_m);}\\

\texttt{soft\_task\_def\_nokill(base\_m);}\\

\texttt{soft\_task\_def\_aperiodic(base\_m);}

\end{description}

\begin{intest}

KEYB\_GETCH, KEYB\_GETCHAR \index{keyb\_getch()} \index{keyb\_getchar()}

\end{intest}

\begin{description}

\item [\textbf{int keyb\_getch(BYTE wait);}]

\item [\textbf{int keyb\_getchar(void);}] (macro)

\item [\textbf{Description:}]If the keyboard queue is not empty,

\texttt{keyb\_getch()} returns the ASCII code of the pressed key. If the queue

is empty, the function's behaviour depends on the value of the \texttt{wait}

parameter: if it is \texttt{BLOCK}, then the calling task is blocked until a key

is pressed; if it is \texttt{NON\_BLOCK}, the function returns 0.

\texttt{keyb\_getchar()} is a macro for \texttt{keyb\_getch(BLOCK)}.

\item [\textbf{Return value:}] the ASCII code of the pressed key, if the buffer

is not empty; 0 otherwise.

\end{description}

\begin{intest}

KEYB\_GETCODE\index{keyb\_getcode()}

\end{intest}

\begin{description}

\item [\texttt{int}]\texttt{keyb\_getcode(KEY\_EVT

{*}k,

BYTE

wait);}

\item [\textbf{Description:}] It fetches the \texttt{KEY\_EVT} from the

keyboard's queue and copies it into the structure pointed by \texttt{k}. If the

queue is empty, the function behaves as \texttt{key\_getch()}.

\item [\textbf{Return value:}] 1 if a key was pressed, 0 otherwise.

\end{description}

\begin{intest}

KEYB\_HOOK\index{keyb\_hook()}

\end{intest}

\begin{description}

\item [\texttt{void}]\texttt{keyb\_hook(KEY\_EVT key, void ({*}hook)(KEY\_EVT

{*}keypressed), unsigned char lock);}

\item [\textbf{Description:}] Whenever the key combination specified in

\texttt{key} is pressed, the function \texttt{hook()} is invoked, getting

\texttt{key} as input parameter. If lock is set to \texttt{FALSE} after

executing the function \texttt{hook()}the key will be lost, otherwise it will be

inserted in the queue.

\end{description}

\begin{description}

\item [Example:]

\end{description}

\begin{verbatim}

#include <drivers/shark_keyb26.h>

void hook_func(KEY_EVT *keypressed) {

    switch (keypressed->ascii) {

        case 'w':

            /* if 'CTRL-w' is pressed... */

            ...

            break;

        case 'x':

            if (isLeftAlt(keypressed) || isRightAlt(keypressed)) {

                /* if 'ALT-x' is pressed... */

                ...

            } else {

                /* if 'x' is pressed... */

                ...

            }

    }

}

int main(int argc,char *argv[]) {

    KEY_EVT key;

    /* keyboard initialization */

    /* to hook 'CTRL-w' key */

    key.ascii = 'w';

    key.scan = KEY_W;

    key.status = KEY_PRESSED;

    key.flag = CNTR_BIT;

    keyb_hook(key,hook_func,FALSE);

    /* to hook key 'x' */

    key.ascii = 'x';

    key.scan = KEY_X;

    key.status = KEY_PRESSED;

    key.flag = 0;

    keyb_hook(key,hook_func, FALSE);

    /* to hook 'ALT-x' key */

    key.flag = ALTL_BIT | ALTR_BIT;

    keyb_hook(key,hook_func, FALSE);

    ...

}

\end{verbatim}

\begin{intest}

KEYB\_DISABLE\index{keyb\_disable()}

\end{intest}

\begin{description}

\item [\textbf{void keyb\_disable(void);}]

\item [\textbf{Description:}] Throw away the data arriving from the hardware

instead of processing them inside the driver.

\end{description}

\begin{intest}

KEYB\_ENABLE\index{keyb\_enable()}

\end{intest}

\begin{description}

\item [\textbf{void keyb\_enable(void);}]

\item [\textbf{Description:}] Allow the driver to receive data from the

hardware.

\end{description}

\begin{intest}

KEYB\_SET\_MAP\index{keyb\_set\_map()}

\end{intest}

\begin{description}

\item [\textbf{int keyb\_set\_map(unsigned char map);}]

\item [\textbf{Description:}] It changes the default map used for the keyboard:

\texttt{map} can be \texttt{KEYMAP\_US} for an english keyboard or

\texttt{KEYMAP\_IT} for an italian keyboard.

\item [\textbf{Return value:}] the keyboard map identifier effectively applied.

\end{description}

\begin{intest}

KEYB\_GET\_MAP\index{keyb\_get\_map()}

\end{intest}

\begin{description}

\item [\texttt{int}]\texttt{keyb\_get\_map(void);}

\item [\textbf{Description:}] Return the identifier of the keyboard map actually

in use.

\end{description}

\begin{intest}

KEY\_EVT\index{KEY\_EVT, structure}

\end{intest}

\begin{description}

\item [\textbf{Description:}] it is a data structure containing the following

fields:

\begin{description}

\item [ascii:]ascii code of the key;

\item [scan:]scan code of the key;

\item [status:]the key can be pressed, repeated or released. When used to set an

hook more than one status can be selected. The \texttt{status} field can be

accessed by one of the following macros, whose usage is self-explaining:

\begin{itemize}

\item isPressed(\&k)

\item isRepeated(\&k)

\item isReleased(\&k)

\end{itemize}

\item [flag:]codes of the ALT, SHIFT and CTRL keys. \\

The \texttt{flag} field can be accessed by one of the following macros, whose

usage is self-explaining:

\begin{itemize}

\item isScanCode(\&k), decides whether the hit key has an ASCII code or not;

\item isLeftShift(\&k)

\item isRightShift(\&k)

\item isLeftAlt(\&k)

\item isRightAlt(\&k)

\item isLeftCtrl(\&k)

\item isRightCtrl(\&k)

\end{itemize}

\end{description}

\end{description}

%----------------------------------------------------------------------------

\section{The mouse library}

%----------------------------------------------------------------------------

To use the mouse into an application program, the user must call the

\texttt{MOUSE26\_init} function. Then, all mouse functions are available until a

call to the \texttt{MOUSE26\_close} function. The initialization of the mouse

library is performed by \texttt{MOUSE26\_init}, which requires a parameter of

\texttt{MOUSE\_PARMS} type to initialize the mouse. The following example shows

a possible mouse initialization:

\begin{verbatim}

int main(int argc,char *argv[]) {

    int result;

    MOUSE_PARMS params = BASE_MOUSE;

    result = MOUSE26_init(&params);

    if (result!=0) {

        // the mouse can't be initialized

    }

    // other mouse functions

    MOUSE26_close();

}

\end{verbatim}

The \texttt{MOUSE26\_close} function is not required but can be used to release

all the hardware resources that the library acquires. The NULL constant can be

passed to the \texttt{MOUSE26\_init()} function for a default initialization.

The \texttt{params} variable can be used to change the default setting of the

initialization procedure using some macros, whose names start with

\texttt{mouse\_def\_}. All the mouse functions can be found in the include file

\texttt{drivers/shark\_mouse26.h}.

\vspace{7mm}

\begin{intest}

MOUSE26\_INIT\index{MOUSE26\_init()}

\end{intest}

\begin{description}

\item [\texttt{int}]\texttt{MOUSE26\_init(KEYB\_PARMS

{*}parms);}

\item [\textbf{Description:}] It initializes the mouse interface and the

library's internal data structures. It can be called using NULL as

\texttt{parms} to initialize the mouse interface to default values.

\item [\textbf{Return value:}] 0 if the operation is performed successfully; a

value less than 0, otherwise.

\end{description}

\begin{intest}

MOUSE26\_CLOSE\index{MOUSE26\_close()}

\end{intest}

\begin{description}

\item [\texttt{int}]\texttt{MOUSE26\_close(void);}

\item [\textbf{Description:}] It

close

the

mouse

interface.

\item [\textbf{Return value:}]

if

the

operation

is

performed

successfully;

-1

if

the

mouse

in

not

installed.

\end{description}

\begin{intest}

MOUSE26\_INSTALLED\index{MOUSE26\_installed()}

\end{intest}

\begin{description}

\item [\texttt{int}]\texttt{MOUSE26\_installed(void);}

\item [\textbf{Description:}] Return

if

the

mouse

driver

is

actually

installed.

\item [\textbf{Return value:}]

if

the

mouse

is

installed;

1

otherwise.

\end{description}

\begin{intest}

MOUSE\_DEFAULT\_PARM\index{mouse\_default\_parm()}

\end{intest}

\begin{description}

\item [\texttt{void}]\texttt{mouse\_default\_parm(KEYB\_PARMS

parms);}

\item [\textbf{Description:}] It

changes

the

values

of

parms

to

the

same

vales

as

the

BASE\_MOUSE

default

initializer.

\end{description}

\begin{intest}

MOUSE\_DEF\_THRESHOLD\index{mousedef\_def\_threshold()}

\end{intest}

\begin{description}

\item [\texttt{void}]\texttt{mouse\_def\_threshold(MOUSE\_PARMS

parms,

int

thr);}

\item [\textbf{Description:}] It

changes

the

default

threshold

(i.e.,

the

mouse

sensitivity)

value

used

in

the

mouse

driver.

Is

a

scaling

factor

between

the

hardware

position

increment

and

the

logical

increment

in

the

mouse

position.

The

higher

the

value,

the

lower

the

sensitivity.

The

default

is

10.

\end{description}

\begin{intest}

MOUSE\_DEF\_X0,

MOUSE\_DEF\_Y0,

MOUSE\_DEF\_Z0\index{mousedef\_def\_x0()} \index{mousedef\_def\_y0()}

\index{mousedef\_def\_z0()}

\end{intest}

\begin{description}

\item [\texttt{void}]\texttt{mouse\_def\_x0(MOUSE\_PARMS

parms,

int

xvalue);}

\item [\texttt{void}]\texttt{mouse\_def\_y0(MOUSE\_PARMS

parms,

int

yvalue);}

\item [\texttt{void}]\texttt{mouse\_def\_z0(MOUSE\_PARMS

parms,

int

zvalue);}

\item [\textbf{Description:}] These

functions

change

the

initial

value

of

the

mouse

position.

The

default

vilue

for

each

parameter

is

if

permitted

by

mouse

position

bounds.

\end{description}

\begin{intest}

MOUSE\_DEF\_XMIN,

MOUSE\_DEF\_XMAX\index{mousedef\_def\_xmin()} \index{mousedef\_def\_xmax()}

\end{intest}

\begin{description}

\item [\texttt{void}]\texttt{mouse\_def\_xmin(MOUSE\_PARMS

parms,

int

minvalue);}

\item [\texttt{void}]\texttt{mouse\_def\_xmax(MOUSE\_PARMS

parms,

int

maxvalue);}

\item [\textbf{Description:}] It

changes

the

minimum

and

maximum

allowed

value

for

the

x

coordinate.

\end{description}

\begin{intest}

MOUSE\_DEF\_YMIN,

MOUSE\_DEF\_YMAX\index{mousedef\_def\_ymin()} \index{mousedef\_def\_ymax()}

\end{intest}

\begin{description}

\item [\texttt{void}]\texttt{mouse\_def\_ymin(MOUSE\_PARMS

parms,

int

minvalue);}

\item [\texttt{void}]\texttt{mouse\_def\_ymax(MOUSE\_PARMS

parms,

int

maxvalue);}

\item [\textbf{Description:}] It

changes

the

minimum

and

maximum

allowed

value

for

the

y

coordinate.

\end{description}

\begin{intest}

MOUSE\_DEF\_TASK\index{mouse\_def\_task()}

\end{intest}

\begin{description}

\item [\texttt{void}]\texttt{mouse\_def\_task(MOUSE\_PARMS

parms,

TASK\_MODEL

{*}

m);}

\item [\textbf{Description:}] This

macro

defines

the

parameters

for

the

mouse

handling

task.

The

\texttt{TASK\_MODEL}

{*}

should

be

a

valid

pointer

to

a

Task

Model,

or

\texttt{MOUSE\_DEFAULT}

if

you

want

to

specify

the

default