diff options
Diffstat (limited to 'doc/dlt_filetransfer.txt')
| -rw-r--r-- | doc/dlt_filetransfer.txt | 250 |
1 files changed, 250 insertions, 0 deletions
diff --git a/doc/dlt_filetransfer.txt b/doc/dlt_filetransfer.txt new file mode 100644 index 0000000..f1878c4 --- /dev/null +++ b/doc/dlt_filetransfer.txt @@ -0,0 +1,250 @@ +DLT Filetransfer +============== +Christian Muck <Christian.Muck@bmw.de> +0.0.1, 2012/10/11: Initial version + +image::images/genivi_chrome_1_transparent.png[width=128] + +Overview +-------- +DLT is a reusable open source software component for standardized logging and tracing in infotainment ECUs based on the AUTOSAR 4.0 standard. +The goal of DLT is the consolidation of the existing variety of logging and tracing protocols on one format. + + +Introduction to DLT Filetransfer +--------------------------------- +With DLT Filetransfer it is possible store the binary data of a file to the automotive dlt log. +The file will be read in binary mode and put as several chunks to a DLT_INFO log. With a special plugin of the dlt viewer, you can extract the embedded files from the trace and save them. +It can be used for smaller files, e.g. HMI screenshots or little coredumps + +Protocol +--------- +The file transfer is at least one single transaction. This transaction consist of three main types of packages: + +* header package +* one or more data packages +* end package + + +Header Package +~~~~~~~~~~~~~~ +Every filetransfer must begin with the header package using: + +---- +int dlt_user_log_file_header(DltContext *fileContext,const char *filename) +---- + +Header Header Package Protocol: + +|================================================================== +| FLST | Package flag +| fileserialnumber | Inode of the file used as file serialnumber +| filename | Use the absolute filepath to the file +| filesize | Filesize of the file +| file creation date | Creation date of the file +| number of packages | Counted packages which will be transferred in the data packages +| BUFFER_SIZE | Defined buffer size to reconstruct the file +| FLST | Package flag +|================================================================== + +Data Package +~~~~~~~~~~~~ +After the header package was sent, at least one or more data packages can be send using: + +---- +int dlt_user_log_file_data(DltContext *fileContext,const char *filename, int packageToTransfer, int timeout) +---- + +Data Data Package Protocol: + +|================================================================== +| FLDA | Package flag +| fileserialnumber | Inode of the file used as file serialnumber +| PackageNumber | Transferred package +| Data | Payload containing data +| FLDA | Package flag +|================================================================== + + +End Package +~~~~~~~~~~~ +After all data packages were sent, the end package must be sent to indicate that the filetransfer is over using: + +---- +int dlt_user_log_file_end(DltContext *fileContext,const char *filename,int deleteFlag) +---- + +End Package Protocol: + +|================================================================== +| FLFI | Package flag +| fileserialnumber | Inode of the file +| FLFI | Package flag +|================================================================== + + +File information +~~~~~~~~~~~~~~~~ +The library offers the user the possibility to log informations about a file using the following method without transferring the file itself using: + +---- +dlt_user_log_file_infoAbout(DltContext *fileContext, const char *filename) +---- + +File Information Protocol: + +|================================================================== +| FLIF | Package flag +| fileserialnumber | Inode of the file used as file serialnumber +| filename | Use the absolute filepath to the file +| filesize | Filesize of the file +| file creation date | Creation date of the file +| number of packages | Counted packages which will be transferred in the data packages +| FLIF | Package flag +|================================================================== + +File transfer error +~~~~~~~~~~~~~~~~~~~ +---- +//! Error code for dlt_user_log_file_complete +#define ERROR_FILE_COMPLETE -300 +//! Error code for dlt_user_log_file_complete +#define ERROR_FILE_COMPLETE1 -301 +//! Error code for dlt_user_log_file_complete +#define ERROR_FILE_COMPLETE2 -302 +//! Error code for dlt_user_log_file_complete +#define ERROR_FILE_COMPLETE3 -303 +//! Error code for dlt_user_log_file_head +#define ERROR_FILE_HEAD -400 +//! Error code for dlt_user_log_file_data +#define ERROR_FILE_DATA -500 +//! Error code for dlt_user_log_file_data +#define DLT_FILETRANSFER_ERROR_FILE_DATA_USER_BUFFER_FAILED -501 +//! Error code for dlt_user_log_file_end +#define ERROR_FILE_END -600 +//! Error code for dlt_user_log_file_infoAbout +#define ERROR_INFO_ABOUT -700 +//! Error code for dlt_user_log_file_packagesCount +#define ERROR_PACKAGE_COUNT -800 +---- + +If an error happens during file transfer, the library will execute the mehtod: + +---- +void dlt_user_log_file_errorMessage(DltContext *fileContext, const char *filename, int errorCode) +---- + +File transfer error Protocol: + +|================================================================== +| FLER | Package flag +| error code | see error codes above +| linux error code | standard linux error code +| fileserialnumber | Inode of the file used as file serialnumber +| filename | Use the absolute filepath to the file +| filesize | Filesize of the file +| file creation date | Creation date of the file +| number of packages | Counted packages which will be transferred in the data packages +| FLER | Package flag +|================================================================== + +If the file doesn't exist, the conent of the error package is a little bit different: + +|================================================================== +| FLER | Package flag +| error code | see error codes above +| linux error code | standard linux error code +| filename | Use the absolute filepath to the file +| FLER | Package flag +|================================================================== + +Using Using DLT Filetransfer +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +There are two ways to use the filetransfer + +* Automatic filetransfer in one step +* Header, data and end package order handeld by the user + +Automatic +~~~~~~~~~ +Call + +* dlt_user_log_file_complete + +The method needs the following arguments: + +* fileContext -> Context for logging the file to dlt +* filename -> Use the absolute file path to the file +* deleteFlag -> Flag if the file will be deleted after transfer. 1->delete, 0->notDelete +* timeout -> Deprecated. + +The order of the packages is to send at first the header, then one or more data packages (depends on the filesize) and in the end the end package. +The advantage of this method is, that you must not handle the package ordering by your own. + +Within dlt_user_log_file_complete the free space of the user buffer will be checked. If the free space of the user buffer < 50% then the +actual package won't be transferred and a timeout will be executed. + +If the daemon crashes and the user buffer is full -> the automatic method is in an endless loop. + +Manual +~~~~~~ +Manual starting filetransfer with the following commands: + +* dlt_user_log_file_head | Transfers only the header of the file +* dlt_user_log_file_data | Transfers only one single package of a file +* dlt_user_log_file_end | Tranfers only the end of the file + +This ordering is very important, so that you can save the transferred files to hard disk on client side with a dlt viewer plugin. +The advantage of using several steps to transfer files by your own is, that you are very flexible to integrate the filetransfer +in your code. + +An other difference to the automatic method is, that only a timeout will be done. There is no check of the user buffer. + +Important Important for integration +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +You should care about blocking the main program when you intergrate filetransfer in your code. +Maybe it's useful to extract the filetransfer in an extra thread. +Another point is the filesize. The bigger the file is, the longer takes it to log the file to dlt. + +Example dlt filetransfer +~~~~~~~~~~~~~~~~~~~~~~~~ +For an example file transfer you can use + +---- +Usage: dlt-example-filetransfer [options] <command> +Filetransfer example with DLT Package Version: 2.2.0 , Package Revision: 1666, build on May 28 2011 02:18:19 +Command: +-f file - File to transfer (absolute path) +Options: +-a apid - Set application id to apid (default: FLTR) +-c ctid - Set context id to ctid (default: FLTR) +-t ms - Timeout between file packages in ms (minimum 20 ms) +-d - Flag to delete the file after the transfer (default: false) +-i - Flag to log file infos to DLT before transfer file (default: false) +-h - This help +---- + +Testing dlt filetransfer +~~~~~~~~~~~~~~~~~~~~~~~~ +When you call "sudo make install", some automatic tests will be installed. Start the test using the following command from bash: + +---- +dlt-test-filetransfer +---- + +It's important that the dlt-filetransfer example files are installed in /usr/share/dlt-filetransfer which will be done automatically by using "sudo make install". + +* testFile1Run1 +Test the file transfer with the condition that the transferred file is smaller as the file transfer buffer using dlt_user_log_file_complete. +* testFile1Run2 +Test the file transfer with the condition that the transferred file is smaller as the file transfer buffer using single package transfer +* testFile2Run1 +Test the file transfer with the condition that the transferred file is bigger as the file transfer buffer using dlt_user_log_file_complete. +* testFile2Run2 +Test the file transfer with the condition that the transferred file is bigger as the file transfer buffer using single package transfer +* testFile3Run1 +Test the file transfer with the condition that the transferred file does not exist using dlt_user_log_file_complete. +* testFile3Run2 +Test the file transfer with the condition that the transferred file does not exist using single package transfer +* testFile3Run3 +Test which logs some information about the file. |