2011-02-17 Joel Sherrill <joel.sherrill@oarcorp.com>

	* libmisc/Makefile.am, libmisc/fb/mw_uid.c, libmisc/fb/mw_uid.h: Clean
	up. Add Doxygen style comments. Add method to print uid structure.
	* libmisc/fb/mw_print.c: New file.

4 files changed, 252 insertions, 117 deletions

diff --git a/cpukit/libmisc/Makefile.am b/cpukit/libmisc/Makefile.am
index 2a7ba78d41..df9010510b 100644
--- a/cpukit/libmisc/Makefile.am
+++ b/cpukit/libmisc/Makefile.am
@@ -62,7 +62,7 @@ EXTRA_DIST += monitor/README
 
 ## fb
 noinst_LIBRARIES += libmw-fb.a
-libmw_fb_a_SOURCES = fb/mw_uid.c fb/fb.h fb/mw_uid.h
+libmw_fb_a_SOURCES = fb/mw_print.c fb/mw_uid.c fb/fb.h fb/mw_uid.h
 
 ## shell
 if LIBSHELL
diff --git a/cpukit/libmisc/fb/mw_print.c b/cpukit/libmisc/fb/mw_print.c
new file mode 100644
index 0000000000..4e8abf2bd8
--- /dev/null
+++ b/cpukit/libmisc/fb/mw_print.c
@@ -0,0 +1,92 @@
+/*
+ *  COPYRIGHT (c) 1989-2011.
+ *  On-Line Applications Research Corporation (OAR).
+ *
+ *  The license and distribution terms for this file may be
+ *  found in the file LICENSE in this distribution or at
+ *  http://www.rtems.com/license/LICENSE.
+ *
+ *  $Id$
+ */
+
+#if HAVE_CONFIG_H
+#include "config.h"
+#endif
+
+#include <rtems/mw_uid.h>
+#include <stdio.h>
+
+const char *uid_buttons(
+  unsigned short  btns,
+  char           *buffer,
+  size_t          max
+)
+{
+  snprintf(
+    buffer,
+    max,
+    "LEFT=%s CENTER=%s RIGHT=%s",
+    ((btns & MV_BUTTON_LEFT) ? "down" : "up"),
+    ((btns & MV_BUTTON_CENTER) ? "down" : "up"),
+    ((btns & MV_BUTTON_RIGHT) ? "down" : "up")
+  );
+  return buffer;
+}
+
+void uid_print_message(
+  struct MW_UID_MESSAGE *uid
+)
+{
+  uid_print_message_with_plugin( NULL, printk_plugin, uid );
+}
+
+void uid_print_message_with_plugin(
+  void                  *context,
+  rtems_printk_plugin_t  handler,
+  struct MW_UID_MESSAGE *uid
+)
+{
+  char buttons[80];
+
+  switch (uid->type) {
+    case MV_UID_INVALID:
+      (*handler)( context, "MV_UID_INVALID\n" );
+      break;
+    case MV_UID_REL_POS:
+      (*handler)(
+        context,
+        "MV_UID_REL_POS - %s x=%d y=%d z=%d\n",
+        uid_buttons( uid->m.pos.btns, buttons, sizeof(buttons)),
+        uid->m.pos.x,    /* x location */
+        uid->m.pos.y,    /* y location */
+        uid->m.pos.z     /* z location, 0 for 2D */
+      );
+      break;
+    case MV_UID_ABS_POS:
+      (*handler)(
+        context,
+        "MV_UID_ABS_POS - %s x=%d y=%d z=%d\n",
+        uid_buttons( uid->m.pos.btns, buttons, sizeof(buttons)),
+        uid->m.pos.x,    /* x location */
+        uid->m.pos.y,    /* y location */
+        uid->m.pos.z     /* z location, 0 for 2D */
+      );
+      break;
+    case MV_UID_KBD:
+      (*handler)( context,
+        "MV_UID_KBD - code=0x%04x modifiers=0x%02x mode=0x%02x\n",
+        uid->m.kbd.code,        /* keycode or scancode        */
+        uid->m.kbd.modifiers,   /* key modifiers              */
+        uid->m.kbd.mode         /* current Kbd mode           */
+      );
+      break;
+   case MV_UID_TIMER:
+      (*handler)( context, "MV_UID_TIMER\n" );
+      break;
+    default:
+      (*handler)( context, "Invalid device type\n" );
+      break;
+  }
+ 
+}
+
diff --git a/cpukit/libmisc/fb/mw_uid.c b/cpukit/libmisc/fb/mw_uid.c
index dcf0e9d9cb..e3cf34f276 100644
--- a/cpukit/libmisc/fb/mw_uid.c
+++ b/cpukit/libmisc/fb/mw_uid.c
@@ -4,9 +4,8 @@
  *
  * MODULE DESCRIPTION:
  * This module implements the input devices interface used by MicroWindows
- * in an embedded system environment.
- * It uses the RTEMS message queue as the repository for the messages posted
- * by the devices registered.
+ * in an embedded system environment.  It uses the RTEMS message queue as
+ * the repository for the messages posted by the devices registered.
  *
  *  $Id$
  */
@@ -24,58 +23,59 @@
 #include <rtems/mw_uid.h>
 #include <rtems/seterr.h>
 
-static rtems_id   queue_id = 0;
-static int open_count = 0;
+static rtems_id  queue_id = 0;
+static int       open_count = 0;
 
 /*
 #define MW_DEBUG_ON     1
 */
 
 /* open a message queue with the kernel */
-int uid_open_queue( const char *q_name, int flags __attribute__((unused)), size_t max_msgs )
+int uid_open_queue(
+  const char *q_name,
+  int         flags __attribute__((unused)),
+  size_t      max_msgs
+)
 {
-   static rtems_name queue_name;
-
-   /*
-    * For the first device calling this function we would create the queue.
-    * It is assumed that this call is done at initialization, and no concerns
-    * regarding multi-threading is taken in consideration here.
-    */
-   if( !open_count )
-   {
-      rtems_status_code status;
-      queue_name = rtems_build_name( q_name[0],
-                                     q_name[1],
-                                     q_name[2],
-                                     q_name[3] );
-      status = rtems_message_queue_create( queue_name,
-                                           max_msgs,
-                                           sizeof( struct MW_UID_MESSAGE ),
-                                           RTEMS_FIFO | RTEMS_LOCAL,
-                                           &queue_id );
-      if( status != RTEMS_SUCCESSFUL )
-      {
-#ifdef MW_DEBUG_ON
-        printk( "UID_Queue: error creating queue: %d\n", status );
-#endif
-        return -1;
-      }
-#ifdef MW_DEBUG_ON
-      printk( "UID_Queue: id=%X\n", queue_id );
-#endif
-   }
-   open_count++;
-   return 0;
+  rtems_status_code status;
+
+  /*
+   * For the first device calling this function we would create the queue.
+   * It is assumed that this call is done at initialization, and no concerns
+   * regarding multi-threading is taken in consideration here.
+   */
+  if ( open_count ) {
+    open_count++;
+    return 0;
+  }
+
+  status = rtems_message_queue_create(
+    rtems_build_name( q_name[0], q_name[1], q_name[2], q_name[3] ),
+    max_msgs,
+    sizeof( struct MW_UID_MESSAGE ),
+    RTEMS_FIFO | RTEMS_LOCAL,
+    &queue_id
+  );
+  if ( status != RTEMS_SUCCESSFUL ) {
+    #ifdef MW_DEBUG_ON
+      printk( "UID_Queue: error creating queue: %d\n", status );
+     #endif
+    return -1;
+  }
+  #ifdef MW_DEBUG_ON
+    printk( "UID_Queue: id=%X\n", queue_id );
+  #endif
+  open_count++;
+  return 0;
 }
 
 
 /* close message queue */
 int uid_close_queue( void )
 {
-  if( open_count == 1 )
-  {
-     rtems_message_queue_delete( queue_id );
-     queue_id = 0;
+  if ( open_count == 1 ) {
+    rtems_message_queue_delete( queue_id );
+    queue_id = 0;
   }
   open_count--;
   return 0;
@@ -86,43 +86,40 @@ int uid_read_message( struct MW_UID_MESSAGE *m, unsigned long timeout )
 {
   rtems_status_code status;
   size_t            size = 0;
-  unsigned long micro_secs = timeout*1000;
-  int wait = ( timeout != 0 );
-
-  status = rtems_message_queue_receive( queue_id,
-                                       (void*)m,
-                                       &size,
-                                       wait ? RTEMS_WAIT : RTEMS_NO_WAIT,
-                                       RTEMS_MICROSECONDS_TO_TICKS(micro_secs));
-
-  if( status == RTEMS_SUCCESSFUL )
-  {
+  unsigned long     micro_secs = timeout*1000;
+  int               wait = (timeout != 0);
+
+  status = rtems_message_queue_receive(
+   queue_id,
+   (void*)m,
+   &size,
+   wait ? RTEMS_WAIT : RTEMS_NO_WAIT,
+   RTEMS_MICROSECONDS_TO_TICKS(micro_secs)
+  );
+
+  if( status == RTEMS_SUCCESSFUL ) {
      return size;
-  }
-  else if( ( status == RTEMS_UNSATISFIED ) || ( status == RTEMS_TIMEOUT ) )
-  {
-     /* this macro returns -1 */
+  } else if( ( status == RTEMS_UNSATISFIED ) || ( status == RTEMS_TIMEOUT ) ) {
      rtems_set_errno_and_return_minus_one( ETIMEDOUT );
   }
   /* Here we have one error condition */
-#ifdef MW_DEBUG_ON
-  printk( "UID_Queue: error reading queue: %d\n", status );
-#endif
+  #ifdef MW_DEBUG_ON
+    printk( "UID_Queue: error reading queue: %d\n", status );
+  #endif
   return -1;
 }
 
-
 /*
- * add a message to the queue of events. This method cna be used to
+ * add a message to the queue of events. This method can be used to
  * simulate hardware events, and it can be very handy during development
  * a new interface.
  */
 int uid_send_message( struct MW_UID_MESSAGE *m )
 {
   rtems_status_code status;
-  status = rtems_message_queue_send( queue_id, ( void * )m,
-                                    sizeof( struct MW_UID_MESSAGE ) );
-  return status == RTEMS_SUCCESSFUL ? 0 : -1;
+  status = rtems_message_queue_send(
+    queue_id, ( void * )m, sizeof( struct MW_UID_MESSAGE ) );
+  return (status == RTEMS_SUCCESSFUL) ? 0 : -1;
 }
 
 /*
@@ -143,13 +140,11 @@ int uid_unregister_device( int fd )
 /* set the keyboard */
 int uid_set_kbd_mode( int fd, int mode, int *old_mode )
 {
-   if (ioctl( fd, MV_KDGKBMODE, old_mode) < 0)
-   {
-      return -1;
-   }
-   if (ioctl(fd, MV_KDSKBMODE, mode ) < 0 )
-   {
-      return -1;
-   }
-   return 0;
+  if (ioctl( fd, MV_KDGKBMODE, old_mode) < 0) {
+     return -1;
+  }
+  if (ioctl(fd, MV_KDSKBMODE, mode ) < 0 ) {
+     return -1;
+  }
+  return 0;
 }
diff --git a/cpukit/libmisc/fb/mw_uid.h b/cpukit/libmisc/fb/mw_uid.h
index 867a28e2e5..89f440acf4 100644
--- a/cpukit/libmisc/fb/mw_uid.h
+++ b/cpukit/libmisc/fb/mw_uid.h
@@ -11,26 +11,26 @@
 #ifndef _MW_UID_H
 #define _MW_UID_H
 
-#ifdef	__cplusplus
+#include <sys/types.h>
+#include <rtems/bspIo.h>
+
+#ifdef __cplusplus
 extern "C" {
 #endif
 
-/* 0x41XX  -- IOCLT functions for the Micro Input Devices commands */
+/* 0x41XX  -- IOCTL functions for the Micro Input Devices commands */
 #define MW_UID_REGISTER_DEVICE     0x4100
 #define MW_UID_UNREGISTER_DEVICE   0x4101
 
-
 /* devices supported by MicroWindows */
-enum MW_INPUT_DEVICE_TYPE
-{
-    MV_UID_INVALID   = 0,
-    MV_UID_REL_POS   = 1,   /* mouse        */
-    MV_UID_ABS_POS   = 2,   /* touch-screen */
-    MV_UID_KBD       = 3,   /* keyboard     */
-    MV_UID_TIMER     = 4    /* timer -- not used */
+enum MW_INPUT_DEVICE_TYPE {
+  MV_UID_INVALID   = 0,
+  MV_UID_REL_POS   = 1,   /* mouse        */
+  MV_UID_ABS_POS   = 2,   /* touch-screen */
+  MV_UID_KBD       = 3,   /* keyboard     */
+  MV_UID_TIMER     = 4    /* timer -- not used */
 };
 
-
 /* matching MicroWindows */
 #define MV_BUTTON_RIGHT                 0x01
 #define MV_BUTTON_CENTER                0x02
@@ -53,43 +53,39 @@ enum MW_INPUT_DEVICE_TYPE
  */
 #define MV_KEY_MODE_SCANCODE            0x00
 
-
 /* these defines match with the linux keyboard range
-   for ioctls functions for the keyboard interface.
-   0x4BXX --- keyboard related functions
+ * for ioctls functions for the keyboard interface.
+ * 0x4BXX --- keyboard related functions
  */
-#define MV_KDGKBMODE	0x4B44   /* gets current keyboard mode */
-#define MV_KDSKBMODE	0x4B45   /* sets current keyboard mode */
+#define MV_KDGKBMODE  0x4B44   /* gets current keyboard mode */
+#define MV_KDSKBMODE  0x4B45   /* sets current keyboard mode */
 
 /*
  * Message generated by input devices controlled by MicroWindows.
  */
-struct MW_UID_MESSAGE
-{
+struct MW_UID_MESSAGE {
   enum MW_INPUT_DEVICE_TYPE type;  /* device type */
-  union
-  {
-     /* fired when keyboard events are raised */
-     struct kbd_t {
-        unsigned short code;        /* keycode or scancode        */
-        unsigned char  modifiers;   /* key modifiers              */
-        unsigned char  mode;        /* current Kbd mode           */
+  union {
+    /* fired when keyboard events are raised */
+    struct kbd_t {
+      unsigned short code;        /* keycode or scancode        */
+      unsigned char  modifiers;   /* key modifiers              */
+      unsigned char  mode;        /* current Kbd mode           */
     } kbd;
 
     /* fired when position events are raised, mouse, touch screen, etc */
     struct pos_t {
-        unsigned short btns; /* indicates which buttons are pressed */
-        short x;             /* x location */
-        short y;             /* y location */
-        short z;             /* z location, 0 for 2D */
+      unsigned short btns; /* indicates which buttons are pressed */
+      short x;             /* x location */
+      short y;             /* y location */
+      short z;             /* z location, 0 for 2D */
     } pos;
 
     /* fired by a timer device periodically */
     struct timer_t {
-        unsigned long  frt;   /* free running timer */
-        unsigned long  seq;   /* sequence number */
+      unsigned long  frt;   /* free running timer */
+      unsigned long  seq;   /* sequence number */
     } tmr;
-
   } m;
 };
 
@@ -105,23 +101,51 @@ struct MW_UID_MESSAGE
  * support.
  */
 
-/* creates the message queue that holds events from the input devices */
+/**
+ *  This method creates the message queue that holds events from the
+ *  input devices.
+ *
+ *  @param[in] q_name is the name of the message queue
+ *  @param[in] flags controls the behaviour of the queue
+ *  @param[in] max_msgs specifies the maximum number of pending messages
+ *
+ *  @note The message queue is from the Classic API.
+ *
+ *  @return This method returns 0 on success and -1 on error.
+ */
 extern int uid_open_queue( const char *q_name, int flags, size_t max_msgs );
 
-/* closes message queue */
+/**
+ *  This method closes the message queue and deletes it.
+ *
+ *  @return This method returns 0 on success and -1 on error.
+ */
 extern int uid_close_queue( void );
 
-/*
- * reads a message from the queue. It waits up to the specified
- * timeout in mili-seconds.
+/**
+ *  This method reads a message from the queue. It waits up to the specified
+ *  timeout in miliseconds. A @a timeout of 0 is a poll.
+ *
+ *  @param[in] m will be filled in with the received message
+ *  @param[in] timeout is the maximum number of mulliseconds to wait
+ *
+ *  @return This method returns 0 on success and -1 on error.
  */
 extern int uid_read_message( struct MW_UID_MESSAGE *m, unsigned long timeout );
 
-/* write a message to the queue */
-extern int uid_write_message( struct MW_UID_MESSAGE *m );
-
+/**
+ *  This methods writes a message to the queue.
+ *
+ *  @param[in] m is the message to send
+ *
+ *  @return This method returns 0 on success and -1 on error.
+ */
+extern int uid_send_message( struct MW_UID_MESSAGE *m );
 
-/* register device to insert data to the queue */
+/**
+ *  This method registers the device associated with @a fd to
+ *  to insert data to the queue
+ */
 extern int uid_register_device( int fd, const char *q_name );
 
 /* unregister device to stop adding messages to the queue */
@@ -130,7 +154,31 @@ extern int uid_unregister_device( int fd );
 /* set the keyboard */
 extern int uid_set_kbd_mode( int fd, int mode, int *old_mode );
 
-#ifdef	__cplusplus
+/**
+ *  This methods prints the specified UID message using printk
+ *
+ *  @param[in] uid points to the message to print
+ */
+void uid_print_message(
+  struct MW_UID_MESSAGE *uid
+);
+
+/**
+ *  This methods prints the specified UID message using your fprintf
+ *  style method of choice.
+ *
+ *  @param[in] context is a pointer to a data area which may be
+ *             used by some print handlers
+ *  @param[in] handler is the fprintf style method to invoke
+ *  @param[in] uid points to the message to print
+ */
+void uid_print_message_with_plugin(
+  void                  *context,
+  rtems_printk_plugin_t  handler,
+  struct MW_UID_MESSAGE *uid
+);
+
+#ifdef __cplusplus
 }
 #endif