From owner-svn-src-all@freebsd.org Fri Aug 21 09:48:01 2020 Return-Path: Delivered-To: svn-src-all@mailman.nyi.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mailman.nyi.freebsd.org (Postfix) with ESMTP id B7C283B884F; Fri, 21 Aug 2020 09:48:01 +0000 (UTC) (envelope-from 0mp@FreeBSD.org) Received: from mxrelay.nyi.freebsd.org (mxrelay.nyi.freebsd.org [IPv6:2610:1c1:1:606c::19:3]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256 client-signature RSA-PSS (4096 bits) client-digest SHA256) (Client CN "mxrelay.nyi.freebsd.org", Issuer "Let's Encrypt Authority X3" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 4BXxXK3y5qz3RQB; Fri, 21 Aug 2020 09:48:01 +0000 (UTC) (envelope-from 0mp@FreeBSD.org) Received: from repo.freebsd.org (repo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:0]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (Client did not present a certificate) by mxrelay.nyi.freebsd.org (Postfix) with ESMTPS id 680182352B; Fri, 21 Aug 2020 09:48:01 +0000 (UTC) (envelope-from 0mp@FreeBSD.org) Received: from repo.freebsd.org ([127.0.1.37]) by repo.freebsd.org (8.15.2/8.15.2) with ESMTP id 07L9m1nO020276; Fri, 21 Aug 2020 09:48:01 GMT (envelope-from 0mp@FreeBSD.org) Received: (from 0mp@localhost) by repo.freebsd.org (8.15.2/8.15.2/Submit) id 07L9m13u020275; Fri, 21 Aug 2020 09:48:01 GMT (envelope-from 0mp@FreeBSD.org) Message-Id: <202008210948.07L9m13u020275@repo.freebsd.org> X-Authentication-Warning: repo.freebsd.org: 0mp set sender to 0mp@FreeBSD.org using -f From: Mateusz Piotrowski <0mp@FreeBSD.org> Date: Fri, 21 Aug 2020 09:48:01 +0000 (UTC) To: src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-head@freebsd.org Subject: svn commit: r364453 - head/usr.sbin/spi X-SVN-Group: head X-SVN-Commit-Author: 0mp X-SVN-Commit-Paths: head/usr.sbin/spi X-SVN-Commit-Revision: 364453 X-SVN-Commit-Repository: base MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-BeenThere: svn-src-all@freebsd.org X-Mailman-Version: 2.1.33 Precedence: list List-Id: "SVN commit messages for the entire src tree \(except for " user" and " projects" \)" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Fri, 21 Aug 2020 09:48:01 -0000 Author: 0mp (doc,ports committer) Date: Fri Aug 21 09:48:00 2020 New Revision: 364453 URL: https://svnweb.freebsd.org/changeset/base/364453 Log: Clean up spi.8 - Remove trailing whitespace - Address igor and mandoc warnings - Sort options - Use macros consistently (e.g., Fl for flags, Dq for quoting, Bd for code blocks) - Add a history section - Fix incorrect use of macros in various places MFC after: 2 weeks Modified: head/usr.sbin/spi/spi.8 Modified: head/usr.sbin/spi/spi.8 ============================================================================== --- head/usr.sbin/spi/spi.8 Fri Aug 21 07:54:16 2020 (r364452) +++ head/usr.sbin/spi/spi.8 Fri Aug 21 09:48:00 2020 (r364453) @@ -1,5 +1,5 @@ .\" Copyright (c) 2018 by S.F.T. Inc. -.\" +.\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: @@ -23,28 +23,28 @@ .\" .\" $FreeBSD$ .\" -.Dd "15 April 2018" -.Dt spi 8 +.Dd August 21, 2020 +.Dt SPI 8 .Os .Sh NAME .Nm spi .Nd communicate on SPI bus with slave devices .Sh SYNOPSIS .Nm -.Op Fl f Ar device -.Op Fl d Ar r|w|rw -.Op Fl m Ar mode -.Op Fl s Ar max-speed -.Op Fl c Ar count -.Op Fl C Ar cmd_bytes .Op Fl A .Op Fl b .Op Fl L .Op Fl v +.Op Fl C Ar command-bytes +.Op Fl c Ar count +.Op Fl d Cm r Ns | Ns Cm w Ns | Ns Cm rw +.Op Fl f Ar device +.Op Fl m Ar mode +.Op Fl s Ar max-speed .Nm .Op Fl i -.Op Fl f Ar device .Op Fl v +.Op Fl f Ar device .Nm .Op Fl h .Sh DESCRIPTION @@ -59,26 +59,26 @@ device. Each .Xr spigen 4 device is associated with a specific -.Sq chip select +.Dq chip select .Pq cs pin on the spibus, and therefore needs to be specified. If no device name is specified on the command line, .Nm assumes -.Sq spigen0.0 . +.Dq spigen0.0 . .Pp For more information on the spigen device, see .Xr spigen 4 . .Pp The options are as follows: -.Bl -tag -width ".Fl f Ar device" +.Bl -tag -width "-f device" .It Fl A Specifies ASCII mode. Both read and write data is input and output as 2-character hexadecimal values, optionally separated by white space, such as 00 01 02 etc. When combined with the -.Sq -b +.Fl b flag, the data on stdin remains a sequence of ASCII hexadecimal byte values, but the output reverts to binary mode. .It Fl b @@ -86,24 +86,23 @@ Binary .Pq output mode. Only has an effect when -.Sq -A +.Fl A has been specified. Reverts the output back to binary .Pq rather than ASCII , while leaving the input format as-is. Use in combination with -.Sq -A +.Fl A to allow using something like -.Sq echo +.Dq echo to pass hexadecimal values to the SPI device, but output the received data on stdout as binary. -.It Fl C Ar command bytes -Sends one or more -.Sq command -bytes, skipping any bytes read-in during the transfer. +.It Fl C Ar command-bytes +Sends one or more command bytes, +skipping any bytes read-in during the transfer. The byte values should be specified as a quoted parameter, similar to the format for data on stdin for -.Sq -A , +.Fl A , that is, 2 character hexadecimal values, optionally separated by white space. An SPI device will typically require that a command be sent, followed by bytes of data. @@ -114,22 +113,23 @@ The total number of bytes to transfer as a decimal int If a write or a read/write transaction is being performed, and fewer than this number of bytes are read in from stdin, the remaining bytes will be sent with a value of -.Sq 0 . +.Dq 0 . If the length can be determined from the input file size, you can use a -.Sq count +.Ar count value of -.Sq -1 +.Dq -1 to base the transfer on the input file's size. -.It Fl d Ar r|w|rw +.It Fl d Cm r Ns | Ns Cm w Ns | Ns Cm rw Transfer direction: Use -.Sq r +.Cm r for read, -.Sq w for write, and -.Sq rw +.Cm w +for write, and +.Cm rw for simultaneous read and write. .It Fl f Ar device SPI device to use -.Pq default is /dev/spigen0 . +.Pq default is Pa /dev/spigen0 . .It Fl h Print help text to stderr, explaining the command line options. .It Fl i @@ -140,8 +140,10 @@ and clock speed are not changed. LSB bit order. The default is MSB, i.e., the highest order bit is transmitted first. -Specifying -L caused the LSB to be transmitted and read first. -.It Fl m Ar 0 - 3 +Specifying +.Fl L +caused the LSB to be transmitted and read first. +.It Fl m Cm 0 Ns | Ns Cm 1 Ns | Ns Cm 2 Ns | Ns Cm 3 SPI mode, 0 through 3. This defines the clock phase and timing with respect to reading and writing data, as per the SPI specification. @@ -153,7 +155,7 @@ exceed this maximum. Specifies Verbose mode. Diagnostics and information are written to stderr. You can specify -.Sq -v +.Fl v more than once to increase verbosity. .El .Sh EXAMPLES @@ -161,43 +163,54 @@ Here are a few examples of using the spi utility: .Bl -bullet .It Get information about the default SPI device -.Pp +.Bd -literal spi -i +.Ed .It Set the maximum clock speed to 200Khz and the mode to 3 on spigen0.1, but do not transmit nor receive any data -.Pp +.Bd -literal spi -f spigen0.1 -s 200000 -m 3 +.Ed .It Send a command sequence consisting of 2 bytes, and read 2 additional bytes from the SPI device, using the current mode and speed on the default device -.Pp +.Bd -literal spi -d r -C "00 01" -c 2 +.Ed .It Transmit a byte value of 5, and receive 2 bytes, displaying their values as 2-byte ASCII hexadecimal, with mode 2, and a maximum clock speed of 500khz. -.Pp +.Bd -literal echo "05" | spi -A -d rw -m 2 -s 500000 -c 2 +.Ed .It Send a binary file, and output the SPI result through -.Sq od +.Xr od 1 as hexadecimal bytes, using the current maximum clock speed and SPI mode. -.Pp +.Bd -literal spi -d rw -c -1