diff options
| author | Eamon Walsh <ewalsh@tycho.nsa.gov> | 2011-06-06 15:33:22 -0400 |
|---|---|---|
| committer | Eamon Walsh <ewalsh@tycho.nsa.gov> | 2011-06-06 15:33:22 -0400 |
| commit | 325e685deb5e6a5f7d1ab98c625d163e8485cfbb (patch) | |
| tree | 3f44900829338bdc1acfd6f414f5984fbaf7520c | |
| parent | 6547f966a768ce88808bc3931c414cf92fde656c (diff) | |
Update file authorship, license, and description in Doxygen style.
Any authorship, copyright, or license information previously present
has been preserved. Where appropriate, this information has also
been propagated to new files (for example from a source file to its
header file).
38 files changed, 822 insertions, 151 deletions
diff --git a/libvchan/init.c b/libvchan/init.c index a810619..4b1f472 100644 --- a/libvchan/init.c +++ b/libvchan/init.c @@ -1,22 +1,31 @@ -/* - * The Qubes OS Project, http://www.qubes-os.org +/** + * @file + * @section AUTHORS * * Copyright (C) 2010 Rafal Wojtczuk <rafal@invisiblethingslab.com> * - * This program is free software; you can redistribute it and/or - * modify it under the terms of the GNU General Public License - * as published by the Free Software Foundation; either version 2 - * of the License, or (at your option) any later version. + * Authors: + * Rafal Wojtczuk <rafal@invisiblethingslab.com> + * Daniel De Graaf <dgdegra@tycho.nsa.gov> * - * This program is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - * GNU General Public License for more details. + * @section LICENSE * - * You should have received a copy of the GNU General Public License - * along with this program; if not, write to the Free Software - * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + * This program is free software; you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation; under version 2 of the License. * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License along + * with this program; if not, write to the Free Software Foundation, Inc., + * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. + * + * @section DESCRIPTION + * + * This file contains the setup code used to establish the ring buffer. */ #include <sys/types.h> diff --git a/libvchan/io.c b/libvchan/io.c index 7ef0289..c3e243c 100644 --- a/libvchan/io.c +++ b/libvchan/io.c @@ -1,22 +1,31 @@ -/* - * The Qubes OS Project, http://www.qubes-os.org +/** + * @file + * @section AUTHORS * * Copyright (C) 2010 Rafal Wojtczuk <rafal@invisiblethingslab.com> * - * This program is free software; you can redistribute it and/or - * modify it under the terms of the GNU General Public License - * as published by the Free Software Foundation; either version 2 - * of the License, or (at your option) any later version. + * Authors: + * Rafal Wojtczuk <rafal@invisiblethingslab.com> + * Daniel De Graaf <dgdegra@tycho.nsa.gov> + * + * @section LICENSE + * + * This program is free software; you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation; under version 2 of the License. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. * - * This program is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - * GNU General Public License for more details. + * You should have received a copy of the GNU General Public License along + * with this program; if not, write to the Free Software Foundation, Inc., + * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. * - * You should have received a copy of the GNU General Public License - * along with this program; if not, write to the Free Software - * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + * @section DESCRIPTION * + * This file contains the communications interface built on the ring buffer. */ #include <sys/types.h> diff --git a/libvchan/libvchan.h b/libvchan/libvchan.h index 67c0ac3..a6c08f4 100644 --- a/libvchan/libvchan.h +++ b/libvchan/libvchan.h @@ -1,22 +1,38 @@ -/* - * The Qubes OS Project, http://www.qubes-os.org +/** + * @file + * @section AUTHORS * * Copyright (C) 2010 Rafal Wojtczuk <rafal@invisiblethingslab.com> * - * This program is free software; you can redistribute it and/or - * modify it under the terms of the GNU General Public License - * as published by the Free Software Foundation; either version 2 - * of the License, or (at your option) any later version. + * Authors: + * Rafal Wojtczuk <rafal@invisiblethingslab.com> + * Daniel De Graaf <dgdegra@tycho.nsa.gov> + * + * @section LICENSE + * + * This program is free software; you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation; under version 2 of the License. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License along + * with this program; if not, write to the Free Software Foundation, Inc., + * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. * - * This program is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - * GNU General Public License for more details. + * @section DESCRIPTION * - * You should have received a copy of the GNU General Public License - * along with this program; if not, write to the Free Software - * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + * Originally borrowed from the Qubes OS Project, http://www.qubes-os.org, + * this code has been substantially rewritten to use the gntdev and gntalloc + * devices instead of raw MFN's and map_foreign_range. * + * This is a library for inter-domain communication. A standard Xen ring + * buffer is used, with a datagram-based interface built on top. The grant + * reference is expected to be shared through some out-of-band mechanism + * such as XenStore. */ #include <stdint.h> diff --git a/libvchan/node-select.c b/libvchan/node-select.c index ce6fa1c..a7c614b 100644 --- a/libvchan/node-select.c +++ b/libvchan/node-select.c @@ -1,22 +1,32 @@ -/* - * The Qubes OS Project, http://www.qubes-os.org +/** + * @file + * @section AUTHORS * * Copyright (C) 2010 Rafal Wojtczuk <rafal@invisiblethingslab.com> * - * This program is free software; you can redistribute it and/or - * modify it under the terms of the GNU General Public License - * as published by the Free Software Foundation; either version 2 - * of the License, or (at your option) any later version. + * Authors: + * Rafal Wojtczuk <rafal@invisiblethingslab.com> + * Daniel De Graaf <dgdegra@tycho.nsa.gov> + * + * @section LICENSE + * + * This program is free software; you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation; under version 2 of the License. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. * - * This program is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - * GNU General Public License for more details. + * You should have received a copy of the GNU General Public License along + * with this program; if not, write to the Free Software Foundation, Inc., + * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. * - * You should have received a copy of the GNU General Public License - * along with this program; if not, write to the Free Software - * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + * @section DESCRIPTION * + * This is a test program for libvchan. Communications are bidirectional, + * with either server (grant offeror) or client able to read and write. */ #include <stdlib.h> diff --git a/libvchan/node.c b/libvchan/node.c index 4d850b0..d00a50f 100644 --- a/libvchan/node.c +++ b/libvchan/node.c @@ -1,22 +1,32 @@ -/* - * The Qubes OS Project, http://www.qubes-os.org +/** + * @file + * @section AUTHORS * * Copyright (C) 2010 Rafal Wojtczuk <rafal@invisiblethingslab.com> * - * This program is free software; you can redistribute it and/or - * modify it under the terms of the GNU General Public License - * as published by the Free Software Foundation; either version 2 - * of the License, or (at your option) any later version. + * Authors: + * Rafal Wojtczuk <rafal@invisiblethingslab.com> + * Daniel De Graaf <dgdegra@tycho.nsa.gov> + * + * @section LICENSE + * + * This program is free software; you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation; under version 2 of the License. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. * - * This program is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - * GNU General Public License for more details. + * You should have received a copy of the GNU General Public License along + * with this program; if not, write to the Free Software Foundation, Inc., + * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. * - * You should have received a copy of the GNU General Public License - * along with this program; if not, write to the Free Software - * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + * @section DESCRIPTION * + * This is a test program for libvchan. Communications are in one direction, + * either server (grant offeror) to client or vice versa. */ #include <stdlib.h> diff --git a/src/bclient.c b/src/bclient.c index 1dcef6d..6a8c8d2 100644 --- a/src/bclient.c +++ b/src/bclient.c @@ -1,3 +1,23 @@ +/** + * @file + * @section AUTHORS + * + * Authors: + * Eamon Walsh <ewalsh@tycho.nsa.gov> + * + * @section LICENSE + * + * This file is in the public domain. + * + * @section DESCRIPTION + * + * This is the "subclass" of display that implements a single view + * consisting of the entirety of a buffer. In other words, this is the + * standard client display for doing a fullscreen framebuffer from a guest. + * With the exception of the combined desktop and the server screen, all + * of the display objects will be of this type. + */ + #include <sys/types.h> #include <stdio.h> #include <stdlib.h> diff --git a/src/buffer.c b/src/buffer.c index 2f31ea2..48dbdca 100644 --- a/src/buffer.c +++ b/src/buffer.c @@ -1,15 +1,33 @@ /** * @file + * @section AUTHORS + * + * Authors: + * Eamon Walsh <ewalsh@tycho.nsa.gov> + * + * @section LICENSE + * + * This file is in the public domain. * * @section DESCRIPTION - * Buffer is the heart of the (virtual) frame buffer memory management routines. It implements a "buffer" as defined by nitpicker; we consider this as more-or-less synonymous with a virtualized frame buffer. It is based upon the original nitpicker buffer code with all of the CORBA calls removed. This file is fairly stable and is not modified often. It does support the following interfaces: * - * buffer *lookup_buffer() - * int nitpicker_import_buffer() - * void nitpicker_remove_buffer() - * void nitpicker_refresh() + * This is the implementation of buffer objects, which represent regions of + * memory, provided by clients, that contain graphical content. * + * There are also two "special" types of buffer that are provided by the + * server itself; these are the background images for the server screen and + * the combined desktop, respectively. All other buffers come from clients + * and, in Linpicker, are associated with framebuffers that are shared out by + * the frontend devices in the guest and which are mapped into Linpicker's + * memory for use. + * + * The implementation here includes the functions to create and manipulate + * buffer objects. The integration of these into the desktop presentation is + * done by the display subsystem, which has various hooks in this code which + * are used to respond to buffer creation and changes; these calls are + * prefixed with display_buffer_. */ + #include <sys/types.h> #include <stdlib.h> #include <stdio.h> diff --git a/src/buffer.h b/src/buffer.h index 724b916..24a4604 100644 --- a/src/buffer.h +++ b/src/buffer.h @@ -1,7 +1,18 @@ /** * @file + * @section AUTHORS + * + * Authors: + * Eamon Walsh <ewalsh@tycho.nsa.gov> + * + * @section LICENSE + * + * This file is in the public domain. + * * @section DESCRIPTION - * This provides the external interface for buffer.c. + * + * This is the implementation of buffer objects, which represent regions of + * memory, provided by clients, that contain graphical content. */ #ifndef _LINPICKER_BUFFER_H_ diff --git a/src/client.c b/src/client.c index 3745195..b748541 100644 --- a/src/client.c +++ b/src/client.c @@ -1,15 +1,33 @@ /** * @file - * @section DESCRIPTION - * This module creates the client representation within the server and manages the client representation. Client is in some ways a misleading name; it is not the client, and is instead purely in the server. - * It does support the following interfaces: + * @section AUTHORS + * + * Copyright (C) 2004-2005 Norman Feske <nf2@os.inf.tu-dresden.de> + * + * Authors: + * Eamon Walsh <ewalsh@tycho.nsa.gov> + * Norman Feske <nf2@inf.tu-dresden.de> + * + * @section LICENSE * + * This program is free software; you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation; under version 2 of the License. * - * client *add_client - * void remove_client - * client *find_client - * int nitpicker_initialize_client + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License along + * with this program; if not, write to the Free Software Foundation, Inc., + * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. + * + * @section DESCRIPTION * + * This is the implementation of client objects, which represent remote + * entities that will provide us with buffer and view objects. In Linpicker, + * there is a one-to-one mapping between client objects and domains. */ #include <sys/types.h> diff --git a/src/client.h b/src/client.h index be74402..298c793 100644 --- a/src/client.h +++ b/src/client.h @@ -1,18 +1,33 @@ /** * @file - * @author Norman Feske <nf2@inf.tu-dresden.de> + * @section AUTHORS + * + * Copyright (C) 2004-2005 Norman Feske <nf2@os.inf.tu-dresden.de> + * + * Authors: + * Eamon Walsh <ewalsh@tycho.nsa.gov> + * Norman Feske <nf2@inf.tu-dresden.de> + * + * @section LICENSE + * + * This program is free software; you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation; under version 2 of the License. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License along + * with this program; if not, write to the Free Software Foundation, Inc., + * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. * * @section DESCRIPTION - * Nitpicker client representation interface - */ - -/* - * Copyright (C) 2002-2005 Norman Feske <nf2@os.inf.tu-dresden.de> - * Technische Universitaet Dresden, Operating Systems Research Group * - * This file is part of the DOpE package, which is distributed under - * the terms of the GNU General Public Licence 2. Please see the - * COPYING file for details. + * This is the implementation of client objects, which represent remote + * entities that will provide us with buffer and view objects. In Linpicker, + * there is a one-to-one mapping between client objects and domains. */ #ifndef _LINPICKER_CLIENT_H_ @@ -1,3 +1,21 @@ +/** + * @file + * @section AUTHORS + * + * Authors: + * Eamon Walsh <ewalsh@tycho.nsa.gov> + * + * @section LICENSE + * + * This file is in the public domain. + * + * @section DESCRIPTION + * + * This is the code that handles incoming libvchan events from linpicker_track. + * This code shoud be robust against bad behavior on the other side, as + * we don't trust the guest that is running linpicker_track. + */ + #include <sys/types.h> #include <stdlib.h> #include <stdio.h> @@ -1,13 +1,27 @@ /** * @file - * @author Mark Rader - * @date 2008-09-07 + * @section AUTHORS * - * @section DESCRIPTION - * Defines structures and enumerated values for interprocess communication. + * Authors: + * Eamon Walsh <ewalsh@tycho.nsa.gov> + * Mark Rader + * + * @section LICENSE + * + * This program is free software; you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation; under version 2 of the License. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License along + * with this program; if not, write to the Free Software Foundation, Inc., + * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. */ - #ifndef _LINPICKER_COMM_H_ #define _LINPICKER_COMM_H_ diff --git a/src/comm_structs.h b/src/comm_structs.h index 7234e31..7918ced 100644 --- a/src/comm_structs.h +++ b/src/comm_structs.h @@ -1,13 +1,27 @@ /** * @file - * @author Mark Rader - * @date 2008-09-07 + * @section AUTHORS * - * @section DESCRIPTION - * Defines structures and enumerated values for interprocess communication. + * Authors: + * Eamon Walsh <ewalsh@tycho.nsa.gov> + * Mark Rader + * + * @section LICENSE + * + * This program is free software; you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation; under version 2 of the License. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License along + * with this program; if not, write to the Free Software Foundation, Inc., + * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. */ - #ifndef _LINPICKER_COMM_STRUCTS_H_ #define _LINPICKER_COMM_STRUCTS_H_ diff --git a/src/common.h b/src/common.h index 3d30fe7..d807ec9 100644 --- a/src/common.h +++ b/src/common.h @@ -1,3 +1,15 @@ +/** + * @file + * @section AUTHORS + * + * Authors: + * Eamon Walsh <ewalsh@tycho.nsa.gov> + * + * @section LICENSE + * + * This file is in the public domain. + */ + #ifndef _LINPICKER_COMMON_H_ #define _LINPICKER_COMMON_H_ diff --git a/src/dclient.c b/src/dclient.c index 600f5e2..c4319a7 100644 --- a/src/dclient.c +++ b/src/dclient.c @@ -1,3 +1,20 @@ +/** + * @file + * @section AUTHORS + * + * Authors: + * Eamon Walsh <ewalsh@tycho.nsa.gov> + * + * @section LICENSE + * + * This file is in the public domain. + * + * @section DESCRIPTION + * + * This is the "subclass" of display that implements the Combined + * Desktop with views from multiple guest framebuffers stacked together. + */ + #include <sys/types.h> #include <sys/select.h> #include <stdio.h> diff --git a/src/debug.c b/src/debug.c index 515cb9a..cd00427 100644 --- a/src/debug.c +++ b/src/debug.c @@ -1,3 +1,21 @@ +/** + * @file + * @section AUTHORS + * + * Authors: + * Eamon Walsh <ewalsh@tycho.nsa.gov> + * + * @section LICENSE + * + * This file is in the public domain. + * + * @section DESCRIPTION + * + * This is the linpicker_cli program that can send debugging commands to + * linpicker_server over a local socket if linpicker_server was compiled + * with the "enable-socket" configure-time option (default: disabled). + */ + #include <sys/types.h> #include <sys/socket.h> #include <sys/un.h> diff --git a/src/display.c b/src/display.c index 725c71d..b72a919 100644 --- a/src/display.c +++ b/src/display.c @@ -1,3 +1,46 @@ +/** + * @file + * @section AUTHORS + * + * Copyright (C) 2002-2004 Norman Feske <nf2@os.inf.tu-dresden.de> + * + * Authors: + * Eamon Walsh <ewalsh@tycho.nsa.gov> + * Norman Feske <nf2@inf.tu-dresden.de> + * + * @section LICENSE + * + * This program is free software; you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation; under version 2 of the License. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License along + * with this program; if not, write to the Free Software Foundation, Inc., + * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. + * + * @section DESCRIPTION + * + * This is the implementation of the DirectFB-based display presentation. + * As buffer and view objects are created and manipulated by clients, callbacks + * are made into this file that update the objects for presentation; these + * callbacks have names prefixed display_buffer_ and display_view_. + * + * A new buffer creation causes an instantiation of a "display object" with 3 + * types: bclient, sclient, or dclient. These are the objects that the + * switcher cycles through. Each object has a list of views associated with + * it, which may originate from different buffers (combined desktop). + * + * This code also handles the secure attention keys that cause the switcher to + * activate, the security bar, view decorations and mouse cursor annotation, + * and the "notification icons" that pop up when events of interest occur, such + * as a client object appearing or disappearing (guest startup/shutdown). + */ + #include <sys/types.h> #include <stdlib.h> #include <stdio.h> diff --git a/src/display.h b/src/display.h index 1248ad2..f88fb5b 100644 --- a/src/display.h +++ b/src/display.h @@ -1,17 +1,27 @@ - -/* - * \brief Nitpicker display interface - * \date 2004-08-24 - * \author Eamon Walsh <ewalsh@tycho.nsa.gov> - */ - -/* - * Copyright (C) 2002-2004 Norman Feske <nf2@os.inf.tu-dresden.de> - * Technische Universitaet Dresden, Operating Systems Research Group +/** + * @file + * @section AUTHORS + * + * Copyright (C) 2002-2004 Norman Feske <nf2@os.inf.tu-dresden.de> + * + * Authors: + * Eamon Walsh <ewalsh@tycho.nsa.gov> + * Norman Feske <nf2@inf.tu-dresden.de> + * + * @section LICENSE + * + * This program is free software; you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation; under version 2 of the License. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. * - * This file is part of the DOpE package, which is distributed under - * the terms of the GNU General Public Licence 2. Please see the - * COPYING file for details. + * You should have received a copy of the GNU General Public License along + * with this program; if not, write to the Free Software Foundation, Inc., + * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. */ #ifndef _LINPICKER_DISPLAY_H_ @@ -1,3 +1,23 @@ +/** + * @file + * @section AUTHORS + * + * Authors: + * Eamon Walsh <ewalsh@tycho.nsa.gov> + * + * @section LICENSE + * + * This file is in the public domain. + * + * @section DESCRIPTION + * + * Two things here: + * 1. Code to redirect stderr into a log file and simple logging functions. + * 2. Generic filehandle tracking code for running a select loop. + * + * This code is shared between linpicker_server and linpicker_monitor. + */ + #define _GNU_SOURCE #include <sys/types.h> #include <sys/select.h> @@ -1,3 +1,15 @@ +/** + * @file + * @section AUTHORS + * + * Authors: + * Eamon Walsh <ewalsh@tycho.nsa.gov> + * + * @section LICENSE + * + * This file is in the public domain. + */ + #ifndef _LINPICKER_FD_H_ #define _LINPICKER_FD_H_ diff --git a/src/input.c b/src/input.c index cb45d79..bb5e83e 100644 --- a/src/input.c +++ b/src/input.c @@ -1,3 +1,23 @@ +/** + * @file + * @section AUTHORS + * + * Authors: + * Eamon Walsh <ewalsh@tycho.nsa.gov> + * + * @section LICENSE + * + * This file is in the public domain. + * + * @section DESCRIPTION + * + * Two things here: + * 1. Udev code to detect new input devices and start monitoring them. + * 2. Handling of raw incoming input events from Linux. The code to detect + * secure key combinations that will be handled by the server (such as the + * switch-between-guests key) is done here, in key_event(). + */ + #include <sys/types.h> #include <sys/select.h> #include <stdlib.h> @@ -261,6 +281,8 @@ err: return -1; } +/* -------------------------------------------------------------------- */ + static void close_device(struct device *d) { diff --git a/src/input.h b/src/input.h index 8d99a37..69b138e 100644 --- a/src/input.h +++ b/src/input.h @@ -1,3 +1,15 @@ +/** + * @file + * @section AUTHORS + * + * Authors: + * Eamon Walsh <ewalsh@tycho.nsa.gov> + * + * @section LICENSE + * + * This file is in the public domain. + */ + #ifndef _LINPICKER_INPUT_H_ #define _LINPICKER_INPUT_H_ diff --git a/src/local.c b/src/local.c index f22eaa0..74bf53c 100644 --- a/src/local.c +++ b/src/local.c @@ -1,3 +1,27 @@ +/** + * @file + * @section AUTHORS + * + * Authors: + * Eamon Walsh <ewalsh@tycho.nsa.gov> + * + * @section LICENSE + * + * This file is in the public domain. + * + * @section DESCRIPTION + * + * This is an optional part of linpicker_server that enables a debugging + * interface over a local socket if the "enable-socket" configure-time option + * is set (default: disabled). + * + * Currently this interface is for debugging (for example dumping the current + * list of views), however this interface might find use in the future as a + * way to control Linpicker programmatically. For example commands could be + * implemented to list the current guests and switch between them, display a + * notification icon, etc. + */ + #include <sys/types.h> #include <sys/socket.h> #include <sys/un.h> diff --git a/src/local.h b/src/local.h index 9fcfc01..997b749 100644 --- a/src/local.h +++ b/src/local.h @@ -1,3 +1,15 @@ +/** + * @file + * @section AUTHORS + * + * Authors: + * Eamon Walsh <ewalsh@tycho.nsa.gov> + * + * @section LICENSE + * + * This file is in the public domain. + */ + #ifndef _LINPICKER_LOCAL_H_ #define _LINPICKER_LOCAL_H_ diff --git a/src/monitor.c b/src/monitor.c index c129b63..661358d 100644 --- a/src/monitor.c +++ b/src/monitor.c @@ -1,3 +1,20 @@ +/** + * @file + * @section AUTHORS + * + * Authors: + * Eamon Walsh <ewalsh@tycho.nsa.gov> + * + * @section LICENSE + * + * This file is in the public domain. + * + * @section DESCRIPTION + * + * This is the main routine for the linpicker_monitor program. + * Nothing much here except initialization, select loop, and teardown. + */ + #include <sys/types.h> #include <stdlib.h> #include <stdio.h> diff --git a/src/sclient.c b/src/sclient.c index 755c724..8e44dec 100644 --- a/src/sclient.c +++ b/src/sclient.c @@ -1,3 +1,21 @@ +/** + * @file + * @section AUTHORS + * + * Authors: + * Eamon Walsh <ewalsh@tycho.nsa.gov> + * + * @section LICENSE + * + * This file is in the public domain. + * + * @section DESCRIPTION + * + * This is the "subclass" of display that implements the server help screen + * (the default screen that has the instructions and allows pressing + * Esc to exit the server). + */ + #include <sys/types.h> #include <stdio.h> #include <stdlib.h> diff --git a/src/sclient.h b/src/sclient.h index 8f96084..b846a1f 100644 --- a/src/sclient.h +++ b/src/sclient.h @@ -1,3 +1,15 @@ +/** + * @file + * @section AUTHORS + * + * Authors: + * Eamon Walsh <ewalsh@tycho.nsa.gov> + * + * @section LICENSE + * + * This file is in the public domain. + */ + #ifndef _LINPICKER_SCLIENT_H_ #define _LINPICKER_SCLIENT_H_ diff --git a/src/server.c b/src/server.c index 033bbe4..92b3d32 100644 --- a/src/server.c +++ b/src/server.c @@ -1,11 +1,19 @@ /** - * @section DESCRIPTION - * nitpicker-server program. This is the main routine that starts - * the linpicker server. + * @file + * @section AUTHORS + * + * Authors: + * Eamon Walsh <ewalsh@tycho.nsa.gov> + * Frank Rehberger <F.Rehberger@xtradyne.de> + * + * @section LICENSE * - * Historically "Hacked from Frank Rehberger - * <F.Rehberger@xtradyne.de>", though there's little of that left. + * This file is in the public domain. + * + * @section DESCRIPTION * + * This is the main routine for the linpicker_server program. + * Nothing much here except initialization, select loop, and teardown. */ #include <sys/types.h> diff --git a/src/track.c b/src/track.c index fef9d72..039622d 100644 --- a/src/track.c +++ b/src/track.c @@ -1,20 +1,37 @@ /** * @file - * @author Norman Feske <nf2@inf.tu-dresden.de> - * @author Edward A. Schneider <ESchneider@ida.org> + * @section AUTHORS + * + * Copyright (C) 2004-2005 Norman Feske <nf2@os.inf.tu-dresden.de> + * + * Authors: + * Eamon Walsh <ewalsh@tycho.nsa.gov> + * Edward A. Schneider <ESchneider@ida.org> + * Norman Feske <nf2@inf.tu-dresden.de> * * @section LICENSE * - * Copyright (C) 2004-2005 Norman Feske <nf2@os.inf.tu-dresden.de> - * Technische Universitaet Dresden, Operating Systems Research Group + * This program is free software; you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation; under version 2 of the License. * - * This file is part of the Overlay WM package, which is distributed - * under the terms of the GNU General Public Licence 2. Please see - * the COPYING file for details. + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License along + * with this program; if not, write to the Free Software Foundation, Inc., + * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. * * @section DESCRIPTION - * This is the code for the Track process, running as part of a Linpicker client, that reports X events related to window management to the Linpicker server * + * This is the linpicker_track program. + * + * The Linpicker version of track has been completely rewritten from scratch. + * The purpose of the program is to keep track of top level X Windows and + * report their position, size, and visibility to linpicker_server via a + * libvchan connection. */ #include <sys/types.h> @@ -1,10 +1,50 @@ /** * @file + * @section AUTHORS + * + * Copyright (C) 2004-2005 Norman Feske <nf2@os.inf.tu-dresden.de> + * + * Authors: + * Eamon Walsh <ewalsh@tycho.nsa.gov> + * Norman Feske <nf2@inf.tu-dresden.de> + * + * @section LICENSE + * + * This program is free software; you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation; under version 2 of the License. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License along + * with this program; if not, write to the Free Software Foundation, Inc., + * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. * * @section DESCRIPTION - * Handle "views" in the server. - * These are rectangular regions of in a screen "buffer", - * which often contain specific windows. + * + * This is the implementation of view objects, which represent rectangular + * regions of a buffer. There are three types of view currently: + * + * 1. Buffer views. When a buffer is created, a default view is also created + * that encompasses the entire buffer. These are used to implement the KVM + * switch mode with one guest shown at a time. + * + * 2. Client views. These are views created by clients that can speak the + * track protocol and use it to indicate where toplevel windows are; these + * views are displayed exclusively on the combined desktop. + * + * 3. Thumbnail views. These are server owned "shadow" views used to implement + * the thumbnails shown in the switcher. One of these is associated with each + * buffer and client view. + * + * The implementation here includes the functions to create and manipulate + * view objects. The integration of these into the desktop presentation is + * done by the display subsystem, which has various hooks in this code which + * are used to respond to view creation and changes; these calls are prefixed + * with display_view_. */ #include <sys/types.h> @@ -1,17 +1,32 @@ - -/* - * \brief Nitpicker view interface - * \date 2004-08-24 - * \author Norman Feske <nf2@inf.tu-dresden.de> - */ - -/* - * Copyright (C) 2002-2004 Norman Feske <nf2@os.inf.tu-dresden.de> - * Technische Universitaet Dresden, Operating Systems Research Group +/** + * @file + * @section AUTHORS + * + * Copyright (C) 2004-2005 Norman Feske <nf2@os.inf.tu-dresden.de> + * + * Authors: + * Eamon Walsh <ewalsh@tycho.nsa.gov> + * Norman Feske <nf2@inf.tu-dresden.de> + * + * @section LICENSE + * + * This program is free software; you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation; under version 2 of the License. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License along + * with this program; if not, write to the Free Software Foundation, Inc., + * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. + * + * @section DESCRIPTION * - * This file is part of the DOpE package, which is distributed under - * the terms of the GNU General Public Licence 2. Please see the - * COPYING file for details. + * This is the implementation of view objects, which represent rectangular + * regions of a buffer. */ #ifndef _LINPICKER_VIEW_H_ diff --git a/src/xen_backend.c b/src/xen_backend.c index 73f1a0b..c466072 100644 --- a/src/xen_backend.c +++ b/src/xen_backend.c @@ -1,6 +1,14 @@ -/* - * xen backend driver infrastructure - * (c) 2008 Gerd Hoffmann <kraxel@redhat.com> +/** + * @file + * @section AUTHORS + * + * Copyright (c) 2008 Gerd Hoffmann <kraxel@redhat.com> + * + * Authors: + * Gerd Hoffmann <kraxel@redhat.com> + * Eamon Walsh <ewalsh@tycho.nsa.gov> + * + * @section LICENSE * * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by @@ -14,10 +22,11 @@ * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. - */ - -/* - * TODO: add some xenbus / xenstore concepts overview here. + * + * @section DESCRIPTION + * + * This is the stock generic backend code from QEMU, modified only slightly. + * This code is shared between linpicker_monitor and linpicker_server. */ #include <sys/types.h> diff --git a/src/xen_backend.h b/src/xen_backend.h index 8a36c75..09683f5 100644 --- a/src/xen_backend.h +++ b/src/xen_backend.h @@ -1,3 +1,34 @@ +/** + * @file + * @section AUTHORS + * + * Copyright (c) 2008 Gerd Hoffmann <kraxel@redhat.com> + * + * Authors: + * Gerd Hoffmann <kraxel@redhat.com> + * Eamon Walsh <ewalsh@tycho.nsa.gov> + * + * @section LICENSE + * + * This program is free software; you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation; under version 2 of the License. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License along + * with this program; if not, write to the Free Software Foundation, Inc., + * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. + * + * @section DESCRIPTION + * + * This is the stock generic backend code from QEMU, modified only slightly. + * This code is shared between linpicker_monitor and linpicker_server. + */ + #ifndef QEMU_HW_XEN_BACKEND_H #define QEMU_HW_XEN_BACKEND_H 1 diff --git a/src/xen_linpicker.h b/src/xen_linpicker.h index 22dd539..83cbdac 100644 --- a/src/xen_linpicker.h +++ b/src/xen_linpicker.h @@ -1,3 +1,41 @@ +/** + * @file + * @section AUTHORS + * + * Copyright IBM, Corp. 2005-2006 + * Copyright Red Hat, Inc. 2006-2008 + * + * Authors: + * Anthony Liguori <aliguori@us.ibm.com>, + * Markus Armbruster <armbru@redhat.com>, + * Daniel P. Berrange <berrange@redhat.com>, + * Pat Campbell <plc@novell.com>, + * Gerd Hoffmann <kraxel@redhat.com> + * Eamon Walsh <ewalsh@tycho.nsa.gov> + * + * @section LICENSE + * + * This program is free software; you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation; under version 2 of the License. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License along + * with this program; if not, write to the Free Software Foundation, Inc., + * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. + * + * @section DESCRIPTION + * + * This is "glue" code between the functions from QEMU and the core + * linpicker_server or linpicker_monitor code. The functions prefixed with + * xen_linpicker_ have differing definitions between server and monitor. + * This header is shared between both programs. + */ + #ifndef _LINPICKER_XEN_H_ #define _LINPICKER_XEN_H_ 1 diff --git a/src/xen_monitor.c b/src/xen_monitor.c index a2ce7d3..83fe1d0 100644 --- a/src/xen_monitor.c +++ b/src/xen_monitor.c @@ -1,3 +1,26 @@ +/** + * @file + * @section AUTHORS + * + * Authors: + * Eamon Walsh <ewalsh@tycho.nsa.gov> + * Daniel De Graaf <dgdegra@tycho.nsa.gov> + * + * @section LICENSE + * + * This file is in the public domain. + * + * @section DESCRIPTION + * + * This is "glue" code between the functions from QEMU and the core + * linpicker_monitor code. The only thing here for linpicker_monitor is the + * domain scanning code that listens in XenStore for new domains starting + * up and handles them (not present in QEMU because each QEMU instance is for + * a single domain). In particular the calls to libxenlight to create the + * initial device backend are made here (which triggers the frontend driver + * to actually set up the device in the guest). + */ + #include <sys/types.h> #include <sys/select.h> #include <stdlib.h> diff --git a/src/xen_server.c b/src/xen_server.c index 8025c04..3cc0a2a 100644 --- a/src/xen_server.c +++ b/src/xen_server.c @@ -1,3 +1,31 @@ +/** + * @file + * @section AUTHORS + * + * Authors: + * Eamon Walsh <ewalsh@tycho.nsa.gov> + * Daniel De Graaf <dgdegra@tycho.nsa.gov> + * + * @section LICENSE + * + * This file is in the public domain. + * + * @section DESCRIPTION + * + * This is "glue" code between the functions from QEMU and the core + * linpicker_server code. There are three main things here: + * + * 1. Libvchan setup, teardown, and processing code that handles the vchan + * communications channel from linpicker_track. + * + * 2. Domain scanning code that listens in XenStore for new domains starting + * up and handles them (not present in QEMU because each QEMU instance is for + * a single domain). + * + * 3. Glue functions for handling events going to and from the frontend, such + * as framebuffer udpate notifications, resizes, and input events. + */ + #include <sys/types.h> #include <sys/select.h> #include <stdlib.h> diff --git a/src/xenfb_monitor.c b/src/xenfb_monitor.c index 3a163f1..0fd6ec5 100644 --- a/src/xenfb_monitor.c +++ b/src/xenfb_monitor.c @@ -1,5 +1,6 @@ -/* - * xen paravirt framebuffer backend +/** + * @file + * @section AUTHORS * * Copyright IBM, Corp. 2005-2006 * Copyright Red Hat, Inc. 2006-2008 @@ -10,6 +11,9 @@ * Daniel P. Berrange <berrange@redhat.com>, * Pat Campbell <plc@novell.com>, * Gerd Hoffmann <kraxel@redhat.com> + * Eamon Walsh <ewalsh@tycho.nsa.gov> + * + * @section LICENSE * * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by @@ -23,6 +27,17 @@ * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. + * + * @section DESCRIPTION + * + * This is the stock framebuffer and input backend code from QEMU, + * modified to call Linpicker instead of QEMU functions. + * + * This is the code for linpicker_monitor, which is responsible for setting + * up the framebuffer and input device backends in XenStore. This code + * acutally only handles XenStore writes during frontend state transitions; + * the initial setup is done using functions from libxenlight. No actual + * servicing of the devices are done here, that is linpicker_server's job. */ #include <sys/types.h> diff --git a/src/xenfb_server.c b/src/xenfb_server.c index 9aee8c4..8935444 100644 --- a/src/xenfb_server.c +++ b/src/xenfb_server.c @@ -1,16 +1,20 @@ -/* - * xen paravirt framebuffer backend +/** + * @file + * @section AUTHORS * * Copyright IBM, Corp. 2005-2006 * Copyright Red Hat, Inc. 2006-2008 * * Authors: + * Eamon Walsh <ewalsh@tycho.nsa.gov> * Anthony Liguori <aliguori@us.ibm.com>, * Markus Armbruster <armbru@redhat.com>, * Daniel P. Berrange <berrange@redhat.com>, * Pat Campbell <plc@novell.com>, * Gerd Hoffmann <kraxel@redhat.com> * + * @section LICENSE + * * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; under version 2 of the License. @@ -23,6 +27,18 @@ * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. + * + * @section DESCRIPTION + * + * This is the stock framebuffer and input backend code from QEMU, + * modified to call Linpicker instead of QEMU functions. + * + * This is the code for linpicker_server, which does not update anything + * in XenStore (that is the job of linpicker_monitor). Rather, this code + * is responsible for waiting until the frontend goes to Connected, then + * mapping the shared pages and framebuffer grant references. Events are + * handled here, with framebuffer updates being sent to Linpicker and input + * events coming from Linpicker sent off to the guest. */ #include <sys/types.h> |