diff options
Diffstat (limited to 'abs/core/local-website/htdocs/mythtv-doc/doxygen-architecture-document.cpp')
| -rw-r--r-- | abs/core/local-website/htdocs/mythtv-doc/doxygen-architecture-document.cpp | 787 |
1 files changed, 787 insertions, 0 deletions
diff --git a/abs/core/local-website/htdocs/mythtv-doc/doxygen-architecture-document.cpp b/abs/core/local-website/htdocs/mythtv-doc/doxygen-architecture-document.cpp new file mode 100644 index 0000000..16ad56d --- /dev/null +++ b/abs/core/local-website/htdocs/mythtv-doc/doxygen-architecture-document.cpp @@ -0,0 +1,787 @@ +/** +\mainpage MythTV Architecture + +\section intro Introduction + +Over the last couple years %MythTV has grown into a rather large +application. The purpose of these pages is to provide a portal +into the code for developers to get their heads around it. +This is intended for both those new to %MythTV and experienced +with it to get familiar with different aspects of the code base. + +If you are just looking for the code formatting standards, +see the official %MythTV wiki article +<a href="http://www.mythtv.org/wiki/index.php/Coding_Standards"> +coding standards</a>. If you are looking for the +<a href="http://svn.mythtv.org/trac/wiki/TicketHowTo">bug tracker</a>, +it can be found on the official pages. +If you haven't already, you should subscribe to +the <a href="http://www.mythtv.org/mailman/listinfo/mythtv-dev/"> +developer mailing list</a> and the <a href="http://www.mythtv.org/mailman/listinfo/mythtv-commits/">SVN commits mailing list</a> + +If you just stumbled onto the developer pages +by accident, maybe you want to go to the official +<a href="http://www.mythtv.org/modules.php?name=MythInstall">%MythTV +Installation page</a>. There is also a good unofficial +<a href="http://wilsonet.com/mythtv/fcmyth.php">Fedora %MythTV installation</a> page, +and a +<a href="http://dev.gentoo.org/~cardoe/mythtv/">Gentoo %MythTV installation</a> page. + +If you are new to Qt programming it is essential that you keep in mind +that almost all Qt objects are not thread-safe, including QString. +Almost all Qt container objects, including QString, make shallow copies +on assignment, the two copies of the object must only be used in one +thread unless you use a lock on the object. You can use the +<a href="http://doc.trolltech.com/3.1/qdeepcopy.html">QDeepCopy</a> +template on most Qt containers to make a copy you can use in another +thread. + +There are also special dangers when +\ref qobject_dangers "using QObject" outside the Qt event thread. + +The is also short HOWTO on \ref profiling_mythtv available in addition +to documentation on the code itself. + +\section libs Libraries + +%MythTV is divided up into eleven libraries: +<dl> + <dt>libmyth <dd>Core %MythTV library. Used by the Plugins. + The \ref database_subsystem "database", + \ref audio_subsystem "audio", + \ref lcd_subsystem "LCD", + \ref osd_subsystem "OSD", + \ref lirc_subsystem "LIRC", and the + \ref myth_network_protocol "myth network protocol" are supported by libmyth. + <dt>libmythtv <dd>%MythTV %TV functionality library. + The + \ref recorder_subsystem "recorders", \ref video_subsystem "video" and + \ref av_player_subsystem "A/V players" are supported by libmythtv. + <dt>libmythui <dd>Main user interface rendering library + <dt>libavcodec/libavformat/libavutil + <dd>This is the ffmpeg A/V decoding library (aka avlib). + <a href="http://ffmpeg.mplayerhq.hu/documentation.html">Documented Externally</a>. + <dt>libmythmpeg2 <dd>Alternate MPEG-1/2 A/V decoding library. + <a href="http://libmpeg2.sourceforge.net/">External Website</a>. + <dt>libmythsamplerate <dd>Audio resampling library + <a href="http://www.mega-nerd.com/SRC/api.html">Documented Externally</a>. + We use this to support a different output sample rates than the sample + rate used in the audio streams we play. + <dt>libmythsoundtouch <dd>Pitch preserving audio resampling library. + <a href="http://www.surina.net/soundtouch/">External Website</a>. + We use this for the time-stretch feature. + <dt>libmythdvdnav + <dd>Used for navigating DVD menus when using the internal player + <dt>libmythfreemheg <dd>UK interactive %TV viewer + <dt>libmythlivemedia <dd>Support for the FreeBox recorder device + <dt>libmythupnp <dd>Initial uPnP (universal Plug and Play) support +</dl> +Two libraries libmythmpeg2 and libmythsamplerate appear redundant, but +libmpeg2 decodes MPEG-2 more quickly than ffmpeg on some systems, and +libmythsamplerate resamples audio with better quality when we only need +to match the hardware sample rate to the A/V streams audio sample rate. + +\section db Database Schema +The database schema is documented here \ref db_schema. + +\section apps Applications +%MythTV contains 14 applications: + +<dl> + <dt>mythbackend <dd>This is the backend which runs the recorders. + <dt>mythfrontend + <dd>This is the frontend which is the main application + for viewing programs and using the %MythTV plugins. + <dt>mythtv-setup <dd>This is the program which sets up the database + to use a machine as a backend server. + <dt>mythtv <dd>This was an "External Player" used to play videos + from within mythfrontend. Setting the player command + to "internal" does the same thing now. This is handy + for testing the audio and videoout code, though. + <dt>mythtvosd + <dd>This is used externally by programs that want to pop-up an + <i>on screen display</i> in %MythTV while one is watching a recording. + <dt>mythfilldatabase + <dd>This is used both internally and externally to fetch program listings. + <a href="http://tms.tribune.com/">Tribune Media</a> provides + listings in exchange for demographic information in the USA, + and Australia uses a + <a href="http://minnie.tuhs.org/twiki/bin/view/TVGuide"> + community-driven TV guide</a> originally developed for OzTiVo. + Other markets are served by the + <a href="http://membled.com/work/apps/xmltv/xmltv">XMLTV</a> + web spiders. + <dt>mythtranscode <dd>This is used both internally and externally to + transcode videos from one format to another. + This is used to shrink HDTV programs to lower + quality recordings that match the hardware the + user has. + <dt>mythjobqueue <dd>This is used internally by mythfrontend to schedule + jobs such as commercial flagging and transcoding. + <dt>mythcommflag <dd>This is used internally by mythfrontend to flag + commercials. + <dt>mythepg <dd>This is used internally by mythfrontend to find + upcoming programs to record based on the channel + and time. + <dt>mythprogfind <dd>This is used internally by mythfrontend to find + programs to record based on the first letter of + the program name. + <dt>mythuitest <dd>This is a test program for libmythui development. + <dt>mythlcdserver <dd>This is an interface between a number of Myth + clients and a small text display (LCDProc server). + <dt>mythwelcome/mythshutdown + <dd>These programs manage Power Saving (shutdown/wakeup) on your Myth PCs. +</dl> + +\section fe_plugins Frontend Plugins +<dl> + <dt>mytharchive <dd>Creates themed Video DVDs from recordings + (and other video files). + <dt>mythbrowser <dd>Provides a simple web browser. + <dt>mythcontrols<dd>Editor for Myth Key bindings, \e et \e c. + <dt>mythflix <dd> + <dt>mythgallery <dd>A simple picture viewer for your %TV. + <dt>mythgame <dd>Launches the xmame classic game system emulator. + <dt>mythmovies <dd> + <dt>mythmusic <dd>A simple music player for your %TV. + <dt>mythnews <dd>Browses RSS news feeds. + <dt>mythphone <dd>SIP based video phone. + <dt>mythvideo <dd>Launch DVD players, and a Video Browser for other files + (non-%MythTV recordings). + <dt>mythweather <dd>Presents your local weather report. + <dt>mythzoneminder<dd> +</dl> + +\section be_plugins Backend Plugins +<dl> + <dt>mythweb <dd>Provides a PHP based web pages to control mythbackend. +</dl> + +\section spt_scripts Support Scripts +These tools are in the contrib directory of the source tree: +<dl> + <dt>osx-packager.pl <dd>Downloads and builds all dependencies, then the + source, of %MythTV and all the official plugins, + on Mac OS 10.3 thru 10.5 + <dt>win32-packager.pl <dd>Similar tool for Windows XP +</dl> + */ + +/** \defgroup database_subsystem Database Subsystem + \todo No one is working on documenting the database subsystem. + +There are a few classes that deal directly with the database: +MythContext, MSqlDatabase, DBStorage, MDBManager, SimpleDBStorage. + +And one function UpgradeTVDatabaseSchema() located in dbcheck.cpp. + +MythTV's Configurable widgets also do save and restore their values +from the database automagically when used in %MythTV's window classes. + */ + +/** \defgroup audio_subsystem Audio Subsystem + \todo Ed W will be documenting the audio subsystem. + */ + +/** \defgroup lcd_subsystem LCD Subsystem + \todo No one is working on documenting the LCD Subsystem + */ + +/** \defgroup osd_subsystem OSD Subsystem + \todo No one is working on documenting the OSD Subsystem + */ + +/** \defgroup lirc_subsystem LIRC Subsystem + \todo No one is working on documenting the LIRC Subsystem + */ + +/** \defgroup video_subsystem Video Subsystem + \todo No one is working on documenting the video subsystem + */ + +/** \defgroup recorder_subsystem Recorder Subsystem +This line is filler that is ignored by Doxygen. + +TVRec is the main class for handling recording. +It is passed a ProgramInfo for the current and next recordings, +and in turn creates three main worker classes: +<dl> + <dt>RecorderBase <dd>Recordings from device into RingBuffer. + <dt>ChannelBase <dd>Changes the channel and other recording device attributes. Optional. + <dt>RingBuffer <dd>Handles A/V file I/O, including streaming. +</dl> + +%TVRec also presents the public face of a recordings to the +\ref myth_network_protocol, and hence the rest of %MythTV. This +means that any call to the %RecorderBase, %RingBuffer, or +%ChannelBase is marshalled via methods in the %TVRec. + +RecorderBase contains classes for recording %MythTV's +specialized Nuppel Video files, as well as classes for +handling various hardware encoding devices such as MPEG2, +HDTV, DVB and Firewire recorders. +ChannelBase meanwhile only contains three subclasses, %Channel +for handling v4l and v4l2 devices, and %DVBChannel and +%FirewireChannel, for handling DVB and Firewire respectively. +Other channel changing hardware use ChannelBase's external +channel changing program support. +Finally, RingBuffer does all reading and writing of A/V files +for both TV (playback) and %TVRec, including streaming +over network connections to the frontend's %RingBuffer. + +%TVRec has four active states, the first three of which +correspond to the same states in %TV: kState_WatchingLiveTV, +kState_WatchingPreRecorded, kState_WatchingRecording, and +kState_RecordingOnly. +When watching "Live TV" the recorder records whatever the +frontend requests and streams it out using the %RingBuffer, +this may be to disk or over the network. +When watching pre-recorded programs %TVRec simply streams a +file on disk out using the %RingBuffer. +When just watching a recording, %TVRec continues a recording +started as recording-only while simultaneously streaming out +using the %RingBuffer. +Finally, when in the recording-only mode the recording +is only saved to disk using %RingBuffer and no streaming +to the frontend is performed. + +%TVRec also has three additional states: kState_Error, +kState_None, kState_ChangingState. The error state allows +%MythTV to know when something has gone wrong. The null or +none state means the recorder is not doing anything and +is ready for commands. Finally, the "ChangingState" state +tells us that a state change request is pending, so other +state changing commands should not be issued. + +\todo Check if the TVRec is actually still passed a ProgramInfo for the current and next recordings + +\todo Document the massive changes Daniel has made in the Vid and MultiRec branches + */ + +/** \defgroup av_player_subsystem A/V Player Subsystem +This line is filler that is ignored by Doxygen. + +TV is the main class for handling playback. +It instantiates several important classes: +<dl> +<dt>NuppelVideoPlayer <dd>Decodes audio and video from the RingBuffer, then plays and displays them, resp. +<dt>RemoteEncoder <dd>Communicates with TVRec on the backend. +<dt>OSD <dd>Creates on-screen-display for NuppelVideoPlayer to display. +<dt>RingBuffer <dd>Handles A/V file I/O, including streaming. +</dl> + +NuppelVideoPlayer is a bit of a misnomer. This class plays all video formats +that %MythTV can handle. It creates AudioOutput to handle the audio, a FilterChain +to perform post-processing on the video, a DecoderBase class to do the actual +video decoding, and a VideoOutput class to do the actual video output. See +that class for more on what it does. + +%TV has three active states that correspond to the same states in TVRec: +kState_WatchingLiveTV, kState_WatchingPreRecorded, kState_WatchingRecording. +When watching "LiveTV" the %TVRec via RemoteEncoder responds to channel +changing and other commands from %TV while streaming the recording to +%TV's %RingBuffer. +When watching a pre-recorded stream, a recording is streamed from TVRec's +%RingBuffer to %TV's %RingBuffer, but no channel changing commands can be +sent to TVRec. +When watching an 'in-progress' recording things work pretty much as when +watching a pre-recorded stream, except %TV must be prevented from seeking +too far ahead in the program, and keyframe and commercial flags must be +synced from the recorder periodically. + +%TV also has three additional states: kState_Error, +kState_None, kState_ChangingState. The error state allows +%MythTV to know when something has gone wrong. The null or +none state means the player is not doing anything and +is ready for commands. Finally, the "ChangingState" state +tells us that a state change request is pending, so other +state changing commands should not be issued. + + */ + +/** \defgroup plugin_arch Plugin Architecture +This line is filler that is ignored by Doxygen. + +MythPlugins are shared object files (<I>i.e.</I> libraries) which are loaded +from a specific directory (<I>%e.g.</I> /usr/local/lib/mythtv/plugins). +Currently, all plugins are written in the C++ language, but there is nothing +preventing other languages being used (the functions are in the C name space). + +int mythplugin_init(const char *libversion); is invoked whenever mythfrontend +is started. This typically handles upgrading any database records - it will be +the first method called after a new version of the plugin has been installed. + +int mythplugin_run(); is invoked when the action attribute of a menu item +requests it via the PLUGIN directive. This is when the user chooses to enter +the plugin from the main menu or the appropriate submenu. + +int mythplugin_config(); is invoked when the action attribute of a menu item +requests it via the CONFIGPLUGIN directive. This should be when the users +wishes to change the plugin's settings (in the main Setup menu). + +Other plugin functions are listed in the file \link mythpluginapi.h \endlink +(see also the \link MythPlugin \endlink + and \link MythPluginManager \endlink classes.) + +*/ + +/** \defgroup mtd MTD (the Myth Transcoding Daemon) +This line is filler that is ignored by Doxygen. + +The %MTD is a simple program that is used by the MythVideo plugin. + +It currently \b only transcodes tracks from DVDs, but could in the +future also rip CD/VCD tracks, transcode %TV recordings, \e et \e cetera. + +The DVD Rip screen will offer to start %MTD if it is not running. +It does \b not currently shut it down afterwards, though. + +By default, the %MTD listens on port 2442, for commands of this format: + +\verbatim +halt +quit +shutdown +\endverbatim +- Tells the %MTD to wait for all jobs to finish, stop listening, and exit. + +\verbatim +hello +\endverbatim +- Send a trivial response if the %MTD is listening. + +\verbatim +status +\endverbatim +<B>\verbatim +status dvd summary 1 +status dvd job 0 overall 0.0262568 ISO copy of UNTITLED +status dvd job 0 subjob 0.0262568 Ripping to file ~ 00:08/05:04 +status dvd complete +\endverbatim</B> +- Sends a response listing the status of all jobs. + +\verbatim +media +\endverbatim +<B>\verbatim +media dvd summary 1 UNTITLED +media dvd title 1 1 1 0 5 27 8 +media dvd title-audio 1 1 2 nl ac3 2Ch +media dvd complete +\endverbatim</B> +- Sends a detailed list of titles/tracks on the current disk. + +\verbatim +job dvd TITLE AUDIOTRK QUALITY AC3 SUBTITLETRK DESTPATH +\endverbatim +\verbatim +e.g. job dvd 1 1 -1 0 -1 /myth/video/UNTITLED +\endverbatim +- Starts a transcoding job. TITLE, AUDIOTRK and SUBTITLETRK are integers + to select the track details. AC3 is 0 or 1. DESTPATH is the output file. + QUALITY is one of enum \ref RIP_QUALITIES (-1, 0 or 1). + +\verbatim +abort dvd job NNNN +\endverbatim +- Stops the job identified by the job number NNNN. + +\verbatim +use dvd PATH +\endverbatim +- Check dvd PATH is usable, and if so set the current drive to it. + +\verbatim +no dvd +\endverbatim +- Forget about the current dvd path, ending any jobs that are trying to read it. + +\verbatim +no dvd PATH +\endverbatim +- End any jobs that are reading from dvd PATH, and if it is the current drive, + forget about it. + */ + +/** \defgroup myth_media Myth Media Manager +This line is filler that is ignored by Doxygen. + +The Myth Media Manager is a thread in the frontend which looks for any +changes to removable media, and sends events to any Frontend Plugins +which are interested in that media. + +At startup, it creates a list of MythMediaDevice objects (currently +MythHDD or MythCDROM and its subclasses) for each removable device +configured on the system. A runtime loop then monitors each of these +via its checkMedia() method. + +When any of these devices change status, a MediaEvent object is created. +If the device has a status which is usable, the window jumps to the main menu +(to allow the registered jump to work correctly), and the event is dispatched +to the relevant plugin's registered media handler. If the device status is +unusable (<I>%e.g.</I> ejected), the plugin's media handler is called directly +(so it can "forget" about this device). + +The following tables show +typical status transitions for CD/DVD and USB flash drive devices: + +\verbatim + CD/DVD USB/FireWire HDD +State Action State Action +-------------------------------------------------- +NODISK NODISK + eject attach +OPEN USEABLE + insert disk, close detach +USEABLE UNPLUGGED + mount +MOUNTED + unmount +NOTMOUNTED +-------------------------------------------------- +\endverbatim + */ + +/** \defgroup myth_network_protocol Myth Network Protocol +This line is filler that is ignored by Doxygen. + +The MythTV backend process currently opens sockets for three different types +of commands; a custom protocol (by default at port 6543), +an HTML server (by default <A HREF="http://127.0.0.1:6544"> +http://127.0.0.1:6544 +</A> for the status, and other services under that, like +< HREF="http://127.0.0.1:6544/Myth/GetMusic?Id=1"> +http://127.0.0.1:6544/Myth/GetMusic?Id=1 +</A>), and a UPnP media server (several ports that I cannot +remember right now that throw around lots of little bits of XML :-) + +The custom protocol is an ASCII encoded length and command string. +Command sequences can be easily sent to the backend using telnet. +<I>%e.g.</I> \verbatim telnet 127.0.0.1 5432 +Trying 127.0.0.1... +Connected to localhost. +Escape character is '^]'.\endverbatim +<B>\verbatim21 MYTH_PROTO_VERSION 36 23 ANN Playback hostname 1 10 QUERY_LOAD 4DONE\endverbatim</B> +\verbatim13 ACCEPT[]:[]362 OK34 0.919922[]:[]0.908203[]:[]0.856445Connection closed by foreign host.\endverbatim +The command string is prefixed by 8 characters, containing the length +of the forthcoming command. This can be justified in any way +(as the above example shows) + +The backend responds with a length, and the response to the command. +This can be numbers (up to 32 bit, represented in ASCII), +a single string, or an ASCII encoding of a QStringList. +The 5 byte sequence "[]:[]" seperates items in the stringlist. +Any 64 bit numbers are represented as a stringlist of two 32bit words +(MSB first). + +\section commands Commands + +There are three main types of networking interactions in MythTV; +identification commands (which tell the backend about this client), +query commands that are sent to the master backend +(<I>%e.g.</I> listing recordings or viewing guide data), and +file streaming commands (when a frontend is watching or editing a recording). + +Until a client is identified to the backend (via the ANN commands), +any of the query or file streaming commands will silently fail. + +The following summarises some of these commands. +For a full understanding of all the commands, either read the source code +(programs/mythbackend/mainserver.cpp), or look on the Wiki +(http://www.mythtv.org/wiki/index.php/Myth_Protocol_Command_List). + + */ + +/** \defgroup qobject_dangers QObject is dangerous for your health +This line is filler that is ignored by Doxygen. + +QObject derived classes can be quite useful, they can send and receive +signals, get keyboard events, translate strings into another language +and use QTimers. + +But they also can't be \ref qobject_delete "deleted" easily, they +are not \ref qobject_threadsafe "thread-safe", can't participate +as equals in multiple \ref qobject_inheritence "inheritence", can +not be used at all in virtual \ref qobject_inheritence "inheritence". + +\section qobject_delete Deleting QObjects + +The problem with deleting QObjects has to do with signals, and events. +These can arrive from any thread, and often arrive from the Qt event +thread even if you have not explicitly requested them. + +If you have not explicitly connected any signals or slots, and the +only events you might get are dispatched with qApp->postEvent(), +not qApp->sendEvent(), then it is safe to delete the QObject in the +Qt event thread. If your QObject is a GUI object you've passed +given to Qt for it to delete all is good. If your object is only +deleted in response to a posted event or a signal from the Qt event +thread (say from a QTimer()) then you are OK as well. + +If your class may be deleted outside a Qt thread, but it does not +explicitly connect any signals or slots, and the only events it +might get are dispatched with qApp->postEvent(), then you can +safely use deleteLater() to queue your object up for deletion +in the event thread. + +%MythTV is a very much a multithreaded program so you may need to have +a QObject that may get events from another thread if you send signals +but do not get any signals and or events from outside the Qt event +thread, then you can use deleteLater() or delete depending on whether +you are deleteing the QObject in the event thread, see above. But +if you are not in the Qt event thread then you need to call disconnect() +in the thread that is sending the signals, before calling deleteLater(). +This prevents your object from sending events after you consider it +deleted (and begin to delete other QObjects that may still be getting +signals from your object.) + +What about if you are getting events via qApp->sendEvent() or a signal +from another thread? In this case things get complicated, so we highly +discourage this in %MythTV and prefer that you use callbacks if at all +possible. But in say you need to do this, then you need to disconnect +all the signals being sent to your QObject. But disconnect() itself +is not atomic. That is you may still get a signal after you disconnect +it. What you need to is disconnect the signal from your slot in the +thread that is sending the signal. This prevents the signal from +being emitted while you are disconnecting. Doing this gracefully is +left as an excersize for the reader. + +Ok, so the above is not entirely complete, for instance you could wrap +every signal emit in an instance lock and reimplement a disconnect +that uses that instance lock. But if you've figured this or another +solution out already all you need to know is that almost all Qt +objects are reenterant but not thread-safe, and that QObjects recieve +events and signals from the Qt event thread and from other threads +if you use qApp->sendEvent() or send signals to it from another thread. + +\section qobject_threadsafe QObject thread-safety + +The only thread-safe classes in Qt are QThread and the mutex classes. +when you call any non-static QObject method you must have a lock on +it or make sure only thread ever calls that function. + +QObject itself is pretty safe because when you assign one QObject to +another you make a copy. Qt's container classes, including QString +do not make a copy but rather pass a reference counted pointer to +the data when you assign one to another. This reference counter is +not protected by a mutex so you can not use regular assignment when +passing a QString or other Qt container from one thread to another. + +In order to use these classes safely you must use +<a href="http://doc.trolltech.com/3.1/qdeepcopy.html">QDeepCopy</a> +when passing them from one thread to another. This is thankfully quite +easy to use. + +\code + QString original = "hello world"; + QString unsafe = original; + QString safe = QDeepCopy<QString>(original); +\endcode + +In this case safe and original can be used by two seperate +threads, while unsafe can only be used in the same thread +as originalStr. + +The QDeepCopy template will work on the most popular Qt containers, +for the ones it doesn't support you will have to copy manually. + +\section qobject_inheritence QObject inheritence + +You can not inherit more than one QObject derived class. +This is because of how signals and slots are implemented. What +happens is that each slot is transformed into an integer that +is used to find the right function pointer quickly when a signal +is sent. But if you have more than one QObject in the inheritence +tree the integers will alias so that signals intended for the +second slot in parent class B might get sent to the second slot +in parent class A instead. Badness ensues. + +For the similar reason you can not inherit a QObject derived +class virtually, in this case the badness is a little more +complicated. The result is the same however, signals arrive +at the wrong slot. Usually, what happens is that the developer +tries to inherit two QObject derived classes but gets linking +errors, so they make one or more of the classes virtual, or +inherit a QObject non-virtually but then also inherit one +or more QObject derived classes virtually. The linker doesn't +complain, but strange unexplainable behaviour ensues when +the application is run and signals start showing up on the +wrong slots. + +*/ + +/** \defgroup profiling_mythtv Profiling MythTV +This line is filler that is ignored by Doxygen. + +You can use any sampling profiler to profile %MythTV, the most +popular GPL one is OProfile and this section tells you how to +use it to profile %MythTV. For Intel also makes VTune, AMD +makes CodeAnalyst, and Apple makes Shark. These all work +similarly to oprofile, so the %MythTV portions are the same. + +This do not describe how to install oprofile. There are a +few cotchas on installation: You must have APIC enabled to +use performance counters. This is usually the default, but +you may want to check this in your kernel configuration. You +also need the oprofile module, this is part of the kernel +config in Linux 2.6+, but must be compiled seperately for +earlier kernels. Finally, some RedHat kernels does not work +with the standard oprofile, so you must use the RedHat +version of oprofile, or compile your own kernel. + + +\section prof_compile Compiling MythTV for profiling + +The first thing you need to do is compile with profiling in +mind. %MythTV has three compile types "release", "debug" and +"profile". The "release" type enables optimizations that +make debugging practically impossible, while "debug" has so +few optimizations that profiling it usually won't tell you +where the real performance problems are. The "profile" compile +type enables the all the optimizations in "release" but also +enables debugging symbols, so that you know which functions +are the CPU hogs. + +So we configure thusly: +\code + make distclean + ./configure --compile-type=profile --enable-proc-opt [+your normal opts] +\endcode + +The "make distclean" clears out all your old binaries and the the configure +sets the compile type approriately. You may not want the "--enable-proc-opt" +if you plan on making a package for other CPUs. This only makes about a +10% difference in playback speed because MMX and CMOV are enabled for +CPUs that support them regardless of this option. + +Next, you compile and install %MythTV as you normally would. +\code + qmake; make -j2 -k + su + make install +\endcode + + +\section prof_init Initializing profiler + +Most sampling profilers, OProfile included, require a kernel module so +this module must be loaded. In oprofile's case the module gets confused +when it has been loaded a long time, so it is best to begin each session +by shutting down the OProfile server and reloading the module: + +\code + opcontrol --deinit + opcontrol --init +\endcode + +You also will want to tell the profiler whether to profile the +kernel as well, if you want the kernel profiled, and assuming +your compiled kernel is in /usr/src/linux, issue this command: +\code + opcontrol --vmlinux=/usr/src/linux/vmlinux +\endcode +If you don't want it in your profile report, use this command: +\code + opcontrol --no-vmlinux +\endcode +Normally, you don't need it when profiling %MythTV, but there are +times when the kernel is a bottleneck. For example when writing +streams to disk is taking too long. + +Now all CPU's are not profiled the same way. In the days of olde, +a sampling profiler would hook into the clock interupt and record +the instuction pointer's location at the instant the interrupt was +triggered. But the wall clock timer still ticks as often as it did +when CPU's ran at 5 Mhz, and now they run almost a thousand times +faster. Such a profile would now take a thousand times longer than +it did in 1985. + +So modern processors include explicit support for profiling. For, +example the Pentium Pro has the INST_RETIRED counter, the Pentium 4 +has the INSTR_RETIRED counter, the AMD64 has the RETIRED_INSNS +counter, etc. For a full list see the +<a href="http://oprofile.sourceforge.net/docs/">OProfile documentation</a>. +You need to find a performance counter you can use for your CPU, +after you've run "opcontrol --init" you can run the following command: +\code + opcontrol --list-events +\endcode +And it will list all the performance counters available with your +CPU. You need to pick the best one for what you want to measure, +for overall performance you want something line INSTR_RETIRED. + +For an Intel Pentium 4, the following will work +\code + opcontrol -e INSTR_RETIRED:6000:0x0f:0:1 +\endcode + +This tells OProfile to schedule an interrupt on every 6000th +instruction that finishes and matches the flag 0x0f. You +could also count cycles when not in idle for the same type of +measurements. The last two numbers tell OProfile it should not +profile the kernel and should profile userspace, if you want +to profile the kernel as well you need to replace the zero with +a one. + +It is possible to profile in oprofile the old fashioned way, by +using the real-time-clock. But you must compile your Linux kernel +WITHOUT RTC support, and run %MythTV significantly longer to get +enough samples for a good report. + + +\section prof_run Running Profiler + +Normally, oprofile will tell you about everything running in +its reports. You can limit what information is collected by +running a opcontrol command such as: +\code + opcontrol --image=/usr/local/bin/mythfrontend +\endcode +This tells OProfile to only profile the frontend. + +Now you want to start %MythTV as usual: + +Then begin doing whatever you want to profile, then issue these +commands: +\code + opcontrol --reset ; opcontrol --start +\endcode + +After a few seconds/minutes your should have collected enough data. +Then you want to issue the following commands: +\code + opcontrol --shutdown + opreport --merge tgid -l --image-path=/usr/local/bin > report.txt +\endcode + +Now you can peruse the report at your pleasure. + +This should be enough to get you started with finding and fixing +performance problems in %MythTV, but there is more information +available from the +<a href=http://oprofile.sourceforge.net/doc/index.html>OProfile manual</a>. +This includes information on constructing callgraphs, producing +an annotated versions of the code, and saving results. + +*/ + +// The file ac3.h in ffmpeg contains no Doxygen markup, +// but for some reason generates the following modules: +// * Coded elements +// * Derived values +// +// They add nothing useful to this programmer doco, so I camouflage these +// by manually defining the block here. Same thing for the few modules +// in ffmpeg that are documented; Macroblock and VC9 bitplanes from vc1.c, +// Monkey Audio from apedec.c, multithreaded slicing from h264.h, + +/** + @defgroup coded . + @defgroup derived . + @defgroup block . + @defgroup std_mb . + @defgroup rangecoder . + @defgroup multithreading . + @defgroup bitplane . + */ |