exprofile_run(connection, varargin)

function profData = exprofile_run(connection, varargin)
%EXPROFILE_RUN collects and displays execution profiling data from a target CPU
%    PROFDATA = EXPROFILE_RUN(CONNECTION) collects and displays execution
%    profiling data from a target microcontroller that is running a suitably
%    configured application. The CONNECTION may be set to 'CAN' in order to
%    collect data via a CAN connection between the target and the host computer,
%    or 'SERIAL' to collect the data via a serial connection. PROFDATA contains
%    the execution profiling data in the format documented by EXPROFILE_UNPACK.
%     
%    PROFDATA = EXPROFILE_RUN(CONNECTION, 'BitRate', BITRATE) sets the BITRATE
%    for the CAN or serial connection to the target. BITRATE must be the same as
%    the bit rate specified for the application that is running on the target.
%
%    To use the CAN connection, you must have suitable CAN hardware
%    installed. This function will test for availability of CanCardX 1 or
%    CanAc2Pci 1 and defaults to a bit rate of 500k bits per second.
%
%    To use the serial connection, the target board must be connected via a
%    serial cable to one of the host computer's serial ports.  This function
%    defaults to port COM1 on the host computer. If the 'BitRate' argument is
%    not provided the default of 57600 baud will be used.
%
%    PROFDATA = EXPROFILE_RUN('serial','SerialPort',SERIALPORT) sets the serial
%    port to the specified SERIALPORT, which should be one of COM1, COM2, etc.
%     
%    The data collected is unpacked then displayed in a summary HTML report 
%    and as MATLAB graphic.
%
%    See also EXPROFILE_GET_DATA_FROM_TARGET1, EXPROFILE_PROCESS_DATA,
%    EXPROFILE_UNPACK, EXPROFILE_GETDATA_CAN, EXPROFILE_GETDATA_SERIAL,
%    EXPROFILE_PLOT, EXPROFILE_REPORT

%   Copyright 2003-2006 The MathWorks, Inc.
%   $Revision: 1.1.2.1 $  $Date: 2006/09/08 14:55:03 $

% Upload the execution profile data

if nargin==0 || ~any(strcmp(lower(connection),{'can','serial'}))
    % Print out a usage message to help the user
    error(sprintf([ mfilename ' requires you to specify a connection '...
                    'to the target board. Available connections '...
                    'are:\n' ...
                    '  ' mfilename '(''can'')\n' ...
                    '  ' mfilename '(''serial'')\n']));
end

rawdata = exprofile_get_data_from_target1(connection, varargin{:});

if ~isempty(rawdata) % No data if time out occurred

    % Data uploaded from the target includes Task id information. Task ids 1, 2, 3,
    % are used to indicate periodic tasks, i.e. the base rate, sub-rate 1,
    % sub-rate 2 etc. Higher value task ids are used to represent non-periodic,
    % i.e. asynchronous tasks. Optionally, a task name may be assigned to the
    % asynchronous task ids; this name will be used in place of the task id in
    % the execution profile report. 
    profileInfo.tasks.names = {...
        'Interrupt 1'...
        'Interrupt 2'...
        'Interrupt 3'...
        'Interrupt 4'...
        'Interrupt 5'...
        'Interrupt 6'...
        'Interrupt 7'...
        'Interrupt 8'...
        'Interrupt 9'...
        'Interrupt 10'...
                   };
    profileInfo.tasks.ids = [ ...
        hex2dec('7FF0')...
        hex2dec('7FF1')...
        hex2dec('7F28')...
        hex2dec('7F29')...
        hex2dec('7F2A')...
        hex2dec('7F2B')...
        hex2dec('7F2C')...
        hex2dec('7F2D')...
        hex2dec('7F2E')...
        hex2dec('7F2F')...
                   ];

    % The raw data uploaded from the target has timer data in counter ticks, i.e. it
    % is uncalibrated; this value defines the base unit of time for converting
    % timer ticks to engineering units.
    profileInfo.timer.timePerTickUnits = 1e-9;
    
    % It is assumed that all counter values have size equal to the target processor
    % word size
    profileInfo.processor.wordsize = 2;
    
    % To decode the counter values the byte ordering on the target processor must be
    % defined
    profileInfo.processor.lsbFirst = 1;
    
    profData = exprofile_process_data(rawdata, profileInfo);
    
end