From c41eceb9d751bdf642d32d2dfc7cb299c85e6467 Mon Sep 17 00:00:00 2001 From: Adam Malinowski Date: Thu, 25 Feb 2016 20:28:17 +0100 Subject: Add man page for sd-mux-ctrl Change-Id: I6e7cfb09a8ff801bed314ba5c77482e828a3896d --- debian/manpages | 1 + doc/man/sd-mux-ctrl.1 | 262 +++++++++++++++++++++++++++++++++++++++++++++ packaging/sd-mux-ctrl.spec | 4 + 3 files changed, 267 insertions(+) create mode 100644 debian/manpages create mode 100644 doc/man/sd-mux-ctrl.1 diff --git a/debian/manpages b/debian/manpages new file mode 100644 index 0000000..8fcb736 --- /dev/null +++ b/debian/manpages @@ -0,0 +1 @@ +doc/man/sd-mux-ctrl.1 diff --git a/doc/man/sd-mux-ctrl.1 b/doc/man/sd-mux-ctrl.1 new file mode 100644 index 0000000..892a475 --- /dev/null +++ b/doc/man/sd-mux-ctrl.1 @@ -0,0 +1,262 @@ +.TH man "22" "February 2016" "0.0.1" "sd-mux-ctrl man page" + +.SH NAME + +.PP +sd-mux-ctrl - control software for sd-mux devices + +.SH SYNOPSIS + +.PP +.B sd-mux-ctrl [-liotdscn?] [-l|--list] [-i|--info] [-u|--status] [-o|--show-serial] [-r|--set-serial=STRING] [-t|--init] [-d|--dut] +.B [-s|--ts] [-p|--pins=INT] [-c|--tick] [-m|--tick-time=INT] [-v|--device-id=INT] [-e|--device-serial=STRING] +.B [-x|--vendor=INT] [-n|--invert] [-?|--help] [--usage] + +.SH DESCRIPTION + +.PP +\fIsd-mux-ctrl\fR is a tool for controlling multiple sd-mux devices. This tool along with the device supports the +following actions: +.RS 2 +1. \fBconnect\fR SD card to DUT (Device Under Test) or to TS (Test Server) +.RE +.RS 2 +2. \fBconnect\fR one USB port to DUT or TS +.RE +.RS 2 +3. \fBpower\fR off/on connected DUT +.RE +.RS 2 +4. \fBreset\fR connected DUT by power disconnecting and reconnecting after specified timeout +.RE +.PP +After manufacturing, each new sd-mux device has VENDOR ID set to 0x0403 which is the ID of FTDI company on whose chip +(FT245RL) the device is based. +Before first real use, the device should be given a unique serial number. +To do that \fB--set-serial\fR command must be executed. \fB--set-serial\fR command writes additional information and +one of them is VENDOR ID. +Since then the device may be used without using \fB--vendor\fR option which is necessary untill the correct VENDOR ID +is set. + +.\" =========================================================================== +.\" Global options +.\" =========================================================================== +.SH OPTIONS + +.PP +-m, \-\-tick-time +.RS 2 +Set period (in milliseconds) for \fB--tick\fR command. +.RE + +.PP +-v, \-\-device-id +.RS 2 +Point at device which is to be used with selected command. Argument for this option is an integer number which is the +id of wanted device. It may be found in the result of \fB--list\fR command. +This method is not recommended for common usage as the id may change after disconnecting and reconnecting devices. +This method may be helpful in particular situations when serial number is not a reliable way of device addressing. +.RE + +.PP +\-e, \-\-device-serial +.RS 2 +Point at device which is to be used with selected command. Argument for this option is a string which is the serial +number of wanted device. It may be found in the result of \fB--list\fR command. +This is the recommended way of addressing devices. +.RE + +.PP +\-x, \-\-vendor +.RS 2 +Set VENDOR ID of devices which are to be used by sd-mux-ctrl. Default value is 0x04e8 which is assigned to +SAMSUNG Electronics Company. DEVICE ID is hard-coded and is equal to 0x6001 - the default FTDI value. +.RE + +.PP +\-n, \-\-invert +.RS 2 +Invert bits given in argument of \fB--pins\fR command. Useful for debugging purposes. +.RE + +.PP +\-h, \-\-help +.RS 2 +Print short help and exit. +.RE + +.PP +\-\-usage +.RS 2 +Print list of command and options and exit. +.RE + +.\" =========================================================================== +.\" Commands descriptions +.\" =========================================================================== +.SH COMMANDS + +.SS \fB\-l, \-\-list\fR + +.RS 2 +Print list of all connected sd-mux devices and exit. It takes optional \fB--vendor\fR argument which allows to use +other VENDOR ID then the default one. +The default value is 0x04e8 which belongs to SAMSUNG Electronics Company. +VENDOR ID is used to discover all connected sd-mux devices. This is very important in post production +(sd-mux device) phase, before first use. +.RE + +.SS \fB\-i, \-\-info\fR + +.RS 2 +Print detailed information about selected device (\fB--device-serial\fR). Sample output of this command: +.nf + +\& VID: 0x04e8 +\& PID: 0x6001 +\& Release: 0x0600 +\& Bus Powered: 90 mA +\& Manufacturer: SRPOL +\& Product: sd-mux +\& Serial: odroid_u3_1 +\& Checksum : ea57 +\& Internal EEPROM +\& PNP: 1 +\& Channel A has Mode UART VCP +\& C0 Function: TXLED +\& C1 Function: RXLED +\& C2 Function: TXDEN +\& C3 Function: PWREN +\& C4 Function: SLEEP + +.fi +Shape of this output depends on libftdi library so may change along with library changes. +.RE + +.SS \fB\-u, \-\-status\fR + +.RS 2 +Print current state of selected device. Example command with output: +.nf + +[tmp]$ \fBsd-mux-ctrl --status --device-serial odroid_u3_1 +USB connected to: DUT +SD connected to: DUT\fR +[tmp]$ + +Or: + +[tmp]$ \fBsd-mux-ctrl --status --device-serial odroid_u3_1 +Device not initialized!\fR +[tmp]$ + +when the device is not initialized after connectig to a host. + +.fi + +.SS \fB\-o, \-\-show-serial\fR + +.RS 2 +Print serial number of selected device. Use \fB--device-id\fR to select wanted device. This command outputs only serial +number, without end of line. +This command is useful actually only for scripts. Example command with output: +.nf + +[sd-mux-ctrl-0.0.1]$ \fBsudo sd-mux-ctrl --device-id=0 --show-serial +minnow_max_1\fR[sd-mux-ctrl-0.0.1]$ +.fi + +.SS \fB\-r, \-\-set-serial\fR + +.RS 2 +Set serial number of selected device. Use \fB--device-id\fR or \fB--device-serial\fR to select wanted device. +Following example changes device's serial number from \fBAL018T40\fR to \fBodrotd_u3_1\fR : +.nf + +[rpm]$ \fBsudo sd-mux-ctrl --device-serial=AL018T40 --vendor=0x403 --set-serial=odroid_u3_1\fR + +.fi +\fB--set-serial\fR command does actually a little bit more than setting a serial number. +It also writes new values of VENDOR ID, Product and Manufacturer. +\fBVENDOR ID (VID)\fR is set to \fB0x04e8\fR (SAMSUNG Electronics Company), Product is set to \fBsd-mux\fR +and \fBManufacturer\fR is set to \fBSRPOL\fR which is a short name of Samsung R&D Poland. + +.SS \fB\-t, \-\-init\fR + +.RS 2 +Set connected device into well defined state. After powering up, sd-mux device is in random state. +SD card and USB may be connected either to DUT or TS. SD card and USB are not tied together so one of them may be +connected to DUT and the other one may be connected to TS. All combinations are possible. +The most important thing here is power steering. As we use bistable, two-coil relay we have to make sure that in stable +state both coils are disconnected from power. +Unfortunately after connecting sd-mux to USB host, state of power control lines is unknown so we have to set them into +correct one. +Init command powers off DUT and connects USB and SD card to TS. Example: +.nf + +[rpm]$ \fBsudo sd-mux-ctrl --device-serial=odroid_u3_1 --init\fR + +.fi + +.SS \fB\-d, \-\-dut\fR + +.RS 2 +Connect USB port and SD card to a DUT (Device Under Test) and power it on. +After executing this command the DUT should start and load image from SD card mounted in the sd-mux device. +.PP +\fBNote\fR that some devices won't (re)start after execution of this command. This is caused by SD multiplexer chip. +When SD is connected to TS then it is actually connected to USB SD card reader. +The reader powers up SD card and some part of the voltage is transmitted to the DUT through SD mux chip. +To force restart one must invoke \fB--tick\fR command after \fB--dut\fR is executed. +Odroiud U3 is an example of device with such behavior. +.nf + +[rpm]$ \fBsudo sd-mux-ctrl --device-serial=odroid_u3_1 --dut\fR +[rpm]$ \fBsudo sd-mux-ctrl --device-serial=odroid_u3_1 --tick\fR + +.fi + +.SS \fB\-s, \-\-ts\fR + +.RS 2 +Connect USB port and SD card to a TS (Test Server) and powers off the DUT (Device Under Test). +After executing this command SD card is connected to SD card reader at the TS side. +.PP +.nf + +[rpm]$ \fBsudo sd-mux-ctrl --device-serial=odroid_u3_1 --ts\fR + +.fi + +.SS \fB\-p, \-\-pins\fR + +.RS 2 +Set FTDI chip (FT245RL) pins to given state. \fB--pins\fR takes 8 bit word as an argument and +optional \fB--invert\fR argument inverts all bits in the given word. +This value, after optional inverting, is written to FT245RL D0-D7 pins. +.PP +.nf + +[rpm]$ \fBsudo sd-mux-ctrl --device-serial=odroid_u3_1 --pins=0x69 --invert\fR + +.fi + +.SS \fB\-c, \-\-tick\fR + +.RS 2 +Disconnect power from the Device Under Test and reconnect again after 1000 ms. +If \fB--tick-time\fR is used, then 1000ms is replaced with number of milliseconds given in \fB--tick-time\fR argument. +.PP +.nf + +[rpm]$ \fBsudo sd-mux-ctrl --device-serial=odroid_u3_1 --tick --tick-time=2000\fR + +.fi + +.SH AUTHOR + +Adam Malinowski . + +.SH REPORTING BUGS + +Please, report bugs to Adam Malinowski . diff --git a/packaging/sd-mux-ctrl.spec b/packaging/sd-mux-ctrl.spec index 367b72a..b285a9c 100644 --- a/packaging/sd-mux-ctrl.spec +++ b/packaging/sd-mux-ctrl.spec @@ -38,5 +38,9 @@ cmake -DCMAKE_INSTALL_PREFIX=/usr rm -rf %{buildroot} %make_install +mkdir -p %{buildroot}/%{_mandir}/man1 +install -m644 docs/man/sd-mux-ctrl.1 %{buildroot}/%{_mandir}/man1 + %files %{_bindir}/%{name} +%{_mandir}/man1/* -- cgit v1.2.3