From nobody Tue Dec 23 13:40:39 2025 X-Original-To: dev-commits-src-all@mlmmj.nyi.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mlmmj.nyi.freebsd.org (Postfix) with ESMTP id 4dbGNl4NcWz6LRHs for ; Tue, 23 Dec 2025 13:40:39 +0000 (UTC) (envelope-from git@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 "R13" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 4dbGNl3dLMz4DBh for ; Tue, 23 Dec 2025 13:40:39 +0000 (UTC) (envelope-from git@FreeBSD.org) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1766497239; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=9AgabJ+/dSeW94Ghbz4e5EIYChu9K9rWHUEOhmx8opY=; b=oFrBn4ZA4lC+MzRHs6tztR3yMTsCcsoyCFtwLvIkTX/SjQS1A2n6k7p9w53kZpEjIW5gS5 9Y6RXG4EEbF8Kzn/CrGk/SMv/VjiDYRksmUY7+Zb9v28wEtEDiMwgOt4+n1i3l5WpjyOv9 se3AAlUAL2Xu4UU/OJcg9VUiT+1QGYaUZVEHM/v1G+02KRUXpAUHfvKfHnpmA1iYhG3bCA 6C3BBRAn9mdnMLNQAyIp2cq6XRERge4qvFRRHogaXxusJT54vMYqTzUUSUNScMwppy4gNv ztrla1zs4d2EvFB0F9/FZBK5bMA46ag56k/pS6F8ba4E/91/0Zw7mSIh8fiK+A== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1766497239; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=9AgabJ+/dSeW94Ghbz4e5EIYChu9K9rWHUEOhmx8opY=; b=OZcF1l3O9Y8TaspUY9vSOvj6qWsPxyN6aIUr5Zab7t1pfLSrJWnfWymNvI6/K/rdsClBgs njTSzWfeQ2sExuz6fm+vQVlK1X/GctJnpOefUmchb/7afRYA8xYS3UiBGoMK8Y8BI+Nflt K549Ouk0Oy8yR2p6u8DS0UbU35JEpKRIWc5SIuDSBtxx0EPsKLq3s3A0cj49enwHUl5yjA I0NQe7HhFRe0fAL8DmCeb2s8RuenGacDfWQCMwELNxb+nzccgKDN4S9jPr8Hxkl92Gl6Zh vqzpORwrkg4s/Vla2PpQqKzzUWnV1T0YYBTecq9BHmjwIzjBUtQZSNX4H31CSw== ARC-Seal: i=1; s=dkim; d=freebsd.org; t=1766497239; a=rsa-sha256; cv=none; b=P+J2+hqVQO4Pe35KmW1HFqD2WCN+KQnimul/Af8XECh9muVRFLCBf/EwQndgKsJsVt1yyN /iA2Q5OpYCkaED3+iAJhxIM97XKTTpaXkYawhjQ+26pwqGCZBGdy4kyb1Xi+kAP92M2rcl tpcebx+q8+WAKT3P5YVaCzpie7DBq/xbr8zqJvyEQnWm0LVJpTImcjKUOi9UWJ345hziMJ A/hUucsA86hIGgbwg1BR1X4F1+w7XYvXnQklWszMCAiws7jBlzd7LetSHbqdpgEmtwkh7s 3W6bDFVWCKJjqsPWZBBHd4L/UpCZLKJs1WmE9LwhkFRgoLXyUI8lHHznKtIXaw== ARC-Authentication-Results: i=1; mx1.freebsd.org; none Received: from gitrepo.freebsd.org (gitrepo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:5]) by mxrelay.nyi.freebsd.org (Postfix) with ESMTP id 4dbGNl2zzXz1CVp for ; Tue, 23 Dec 2025 13:40:39 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from git (uid 1279) (envelope-from git@FreeBSD.org) id 38536 by gitrepo.freebsd.org (DragonFly Mail Agent v0.13+ on gitrepo.freebsd.org); Tue, 23 Dec 2025 13:40:39 +0000 To: src-committers@FreeBSD.org, dev-commits-src-all@FreeBSD.org, dev-commits-src-main@FreeBSD.org From: Alexander Ziaee Subject: git: fbc321b9cdce - main - camcontrol.8: Descriptions before examples List-Id: Commit messages for all branches of the src repository List-Archive: https://lists.freebsd.org/archives/dev-commits-src-all List-Help: List-Post: List-Subscribe: List-Unsubscribe: X-BeenThere: dev-commits-src-all@freebsd.org Sender: owner-dev-commits-src-all@FreeBSD.org MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Git-Committer: ziaee X-Git-Repository: src X-Git-Refname: refs/heads/main X-Git-Reftype: branch X-Git-Commit: fbc321b9cdceecd3c97742868da5d500423cf484 Auto-Submitted: auto-generated Date: Tue, 23 Dec 2025 13:40:39 +0000 Message-Id: <694a9bd7.38536.453fe7f5@gitrepo.freebsd.org> The branch main has been updated by ziaee: URL: https://cgit.FreeBSD.org/src/commit/?id=fbc321b9cdceecd3c97742868da5d500423cf484 commit fbc321b9cdceecd3c97742868da5d500423cf484 Author: Alexander Ziaee AuthorDate: 2025-12-23 13:36:49 +0000 Commit: Alexander Ziaee CommitDate: 2025-12-23 13:40:29 +0000 camcontrol.8: Descriptions before examples This page has a lot of examples, so having them in the previous order can be confusing. Rewrite to the normal order where the descriptions come before the command, followed by a colon, which is still clear even jumping to the middle of the section. PR: 291759 MFC after: 3 days Reviewed by: imp Differential Revision: https://reviews.freebsd.org/D54285 --- sbin/camcontrol/camcontrol.8 | 349 ++++++++++++++++++------------------------- 1 file changed, 148 insertions(+), 201 deletions(-) diff --git a/sbin/camcontrol/camcontrol.8 b/sbin/camcontrol/camcontrol.8 index bdda1828abf5..4963615fe6f6 100644 --- a/sbin/camcontrol/camcontrol.8 +++ b/sbin/camcontrol/camcontrol.8 @@ -2684,303 +2684,250 @@ is the transport layer device. are the CAM application passthrough devices. .El .Sh EXAMPLES -.Dl camcontrol eject -n cd -u 1 -v -.Pp Eject the CD from cd1, and print SCSI sense information if the command -fails. +fails: .Pp -.Dl camcontrol tur da0 +.Dl camcontrol eject -n cd -u 1 -v .Pp Send the SCSI test unit ready command to da0. The .Nm -utility will report whether the disk is ready, but will not display sense -information if the command fails since the +utility will report whether the disk is ready, +but will not display sense information if the command fails since the .Fl v -switch was not specified. -.Bd -literal -offset indent -camcontrol tur da1 -E -C 4 -t 50 -Q head -v -.Ed +switch was not specified: +.Pp +.Dl camcontrol tur da0 .Pp Send a test unit ready command to da1. Enable kernel error recovery. Specify a retry count of 4, and a timeout of 50 seconds. -Enable sense -printing (with the -.Fl v -flag) if the command fails. -Since error recovery is turned on, the -disk will be spun up if it is not currently spinning. -The -.Tn SCSI -task attribute for the command will be set to Head of Queue. +Enable sense printing +.Pq with the Fl v flag +if the command fails. +Since error recovery is turned on, +the disk will be spun up if it is not currently spinning. +The SCSI task attribute for the command will be set to Head of Queue. The .Nm -utility will report whether the disk is ready. -.Bd -literal -offset indent -camcontrol cmd -n cd -u 1 -v -c "3C 00 00 00 00 00 00 00 0e 00" \e - -i 0xe "s1 i3 i1 i1 i1 i1 i1 i1 i1 i1 i1 i1" -.Ed +utility will report whether the disk is ready: +.Pp +.Dl camcontrol tur da1 -E -C 4 -t 50 -Q head -v .Pp Issue a READ BUFFER command (0x3C) to cd1. Display the buffer size of cd1, and display the first 10 bytes from the cache on cd1. -Display SCSI sense -information if the command fails. +Display SCSI sense information if the command fails: .Bd -literal -offset indent -camcontrol cmd -n cd -u 1 -v -c "3B 00 00 00 00 00 00 00 0e 00" \e - -o 14 "00 00 00 00 1 2 3 4 5 6 v v v v" 7 8 9 8 +camcontrol cmd -n cd -u 1 -v -c "3C 00 00 00 00 00 00 00 0e 00" \e + -i 0xe "s1 i3 i1 i1 i1 i1 i1 i1 i1 i1 i1 i1" .Ed .Pp Issue a WRITE BUFFER (0x3B) command to cd1. Write out 10 bytes of data, not including the (reserved) 4 byte header. -Print out sense information if -the command fails. -Be very careful with this command, improper use may -cause data corruption. +Print out sense information if the command fails. +Be very careful with this command, +improper use may cause data corruption: .Bd -literal -offset indent -camcontrol modepage da3 -m 1 -e -P 3 +camcontrol cmd -n cd -u 1 -v -c "3B 00 00 00 00 00 00 00 0e 00" \e + -o 14 "00 00 00 00 1 2 3 4 5 6 v v v v" 7 8 9 8 .Ed .Pp -Edit mode page 1 (the Read-Write Error Recover page) for da3, and save the -settings on the drive. +Edit mode page 1 (the Read-Write Error Recover page) for da3, +and save the settings on the drive. Mode page 1 contains a disk drive's auto read and -write reallocation settings, among other things. +write reallocation settings, among other things: +.Bd -literal -offset indent +camcontrol modepage da3 -m 1 -e -P 3 +.Ed +.Pp +Rescan all SCSI buses in the system for devices that have been added, +removed or changed: .Pp .Dl camcontrol rescan all .Pp -Rescan all SCSI buses in the system for devices that have been added, -removed or changed. +Rescan SCSI bus 0 for devices that have been added, removed or changed: .Pp .Dl camcontrol rescan 0 .Pp -Rescan SCSI bus 0 for devices that have been added, removed or changed. +Rescan SCSI bus 0, target 1, lun 0 to see if it has been added, removed, +or changed: .Pp .Dl camcontrol rescan 0:1:0 .Pp -Rescan SCSI bus 0, target 1, lun 0 to see if it has been added, removed, or -changed. +Set the number of concurrent transactions for da5 to 24: .Pp .Dl camcontrol tags da5 -N 24 .Pp -Set the number of concurrent transactions for da5 to 24. -.Bd -literal -offset indent -camcontrol negotiate -n da -u 4 -T disable -.Ed +Disable tagged queueing for da4: .Pp -Disable tagged queueing for da4. -.Bd -literal -offset indent -camcontrol negotiate -n da -u 3 -R 20.000 -O 15 -a -.Ed +.Dl camcontrol negotiate -n da -u 4 -T disable .Pp Negotiate a sync rate of 20MHz and an offset of 15 with da3. -Then send a -Test Unit Ready command to make the settings take effect. -.Bd -literal -offset indent -camcontrol smpcmd ses0 -v -r 4 "40 0 00 0" -R 1020 "s9 i1" -.Ed +Then send a Test Unit Ready command to make the settings take effect: .Pp -Send the SMP REPORT GENERAL command to ses0, and display the number of PHYs -it contains. -Display SMP errors if the command fails. -.Bd -literal -offset indent -camcontrol security ada0 -.Ed +.Dl camcontrol negotiate -n da -u 3 -R 20.000 -O 15 -a .Pp -Report security support and settings for ada0 -.Bd -literal -offset indent -camcontrol security ada0 -U user -s MyPass -.Ed +Send the SMP REPORT GENERAL command to ses0, +and display the number of PHYs it contains, +displaying SMP errors if the command fails: .Pp -Enable security on device ada0 with the password MyPass -.Bd -literal -offset indent -camcontrol security ada0 -U user -e MyPass -.Ed +.Dl camcontrol smpcmd ses0 -v -r 4 "40 0 00 0" -R 1020 "s9 i1" .Pp -Secure erase ada0 which has had security enabled with user password MyPass +Report security support and settings for ada0: .Pp -.Em WARNING! WARNING! WARNING! +.Dl camcontrol security ada0 +.Pp +Enable security on device ada0 with the password MyPass: +.Pp +.Dl camcontrol security ada0 -U user -s MyPass +.Pp +Secure erase the security enabled ada0 with user password MyPass. .Pp -This will +.Em WARNING ! WARNING ! WARNING ! +.Pp +The following command will .Em ERASE ALL data from the device, so backup your data before using! .Pp -This command can be used against an SSD drive to restoring it to -factory default write performance. -.Bd -literal -offset indent -camcontrol hpa ada0 -.Ed +This will restore a solid state drive +.Pq SSD +to factory default write performance: .Pp -Report HPA support and settings for ada0 (also reported via -identify). -.Bd -literal -offset indent -camcontrol hpa ada0 -s 10240 -.Ed +.Dl camcontrol security ada0 -U user -e MyPass .Pp -Enables HPA on ada0 setting the maximum reported sectors to 10240. +Report HPA support and settings for ada0 (also reported via identify): .Pp -.Em WARNING! WARNING! WARNING! +.Dl camcontrol hpa ada0 +.Pp +Enable HPA on ada0 setting the maximum reported sectors to 10240. +.Pp +.Em WARNING ! WARNING ! WARNING ! .Pp -This will +The following command will .Em PREVENT ACCESS -to all data on the device beyond this limit until HPA is disabled by setting -HPA to native max sectors of the device, which can only be done after a -power-on or hardware reset! +to all data on the device beyond this limit until HPA is disabled +by setting HPA to native max sectors of the device, +which can only be done after a power-on or hardware reset! .Pp .Em DO NOT -use this on a device which has an active filesystem! -.Bd -literal -offset indent -camcontrol persist da0 -v -i read_keys -.Ed +use this on a device which has an active filesystem: .Pp -This will read any persistent reservation keys registered with da0, and -display any errors encountered when sending the PERSISTENT RESERVE IN -.Tn SCSI -command. -.Bd -literal -offset indent -camcontrol persist da0 -v -o register -a -K 0x12345678 -.Ed +.Dl camcontrol hpa ada0 -s 10240 .Pp -This will register the persistent reservation key 0x12345678 with da0, -apply that registration to all ports on da0, and display any errors that -occur when sending the PERSISTENT RESERVE OUT command. -.Bd -literal -offset indent -camcontrol persist da0 -v -o reserve -s lun -k 0x12345678 -T ex_ac -.Ed +This will read any persistent reservation keys registered with da0, +and display any errors encountered when sending the +PERSISTENT RESERVE IN SCSI command: .Pp -This will reserve da0 for the exlusive use of the initiator issuing the -command. +.Dl camcontrol persist da0 -v -i read_keys +.Pp +Register the persistent reservation key 0x12345678 with da0, +apply that registration to all ports on da0, +and display any errors that +occur when sending the PERSISTENT RESERVE OUT command: +.Pp +.Dl camcontrol persist da0 -v -o register -a -K 0x12345678 +.Pp +Reserve da0 for the exclusive use of the initiator issuing the command. The scope of the reservation is the entire LUN. -Any errors sending the PERSISTENT RESERVE OUT command will be displayed. -.Bd -literal -offset indent -camcontrol persist da0 -v -i read_full -.Ed +Any errors sending the PERSISTENT RESERVE OUT command will be displayed: .Pp -This will display the full status of all reservations on da0 and print out -status if there are any errors. -.Bd -literal -offset indent -camcontrol persist da0 -v -o release -k 0x12345678 -T ex_ac -.Ed +.Dl camcontrol persist da0 -v -o reserve -s lun -k 0x12345678 -T ex_ac +.Pp +Display the full status of all reservations on da0 +and print out status if there are any errors: +.Pp +.Dl camcontrol persist da0 -v -i read_full .Pp This will release a reservation on da0 of the type ex_ac -(Exclusive Access). +.Pq Exclusive Access . The Reservation Key for this registration is 0x12345678. -Any errors that occur will be displayed. +Any errors that occur will be displayed: +.Pp +.Dl camcontrol persist da0 -v -o release -k 0x12345678 -T ex_ac +.Pp +Register the key 0x12345678 with da0, +specifying that it applies to the SAS initiators +with SAS addresses 0x1234567812345678 and 0x8765432187654321: .Bd -literal -offset indent camcontrol persist da0 -v -o register -K 0x12345678 -S \e -I sas,0x1234567812345678 -I sas,0x8765432187654321 .Ed .Pp -This will register the key 0x12345678 with da0, specifying that it applies -to the SAS initiators with SAS addresses 0x1234567812345678 and -0x8765432187654321. -.Bd -literal -offset indent -camcontrol persist da0 -v -o register_move -k 0x87654321 \e - -K 0x12345678 -U -p -R 2 -I fcp,0x1234567812345678 -.Ed -.Pp -This will move the registration from the current initiator, whose -Registration Key is 0x87654321, to the Fibre Channel initiator with the +Move the registration from the current initiator, +whose Registration Key is 0x87654321, +to the Fibre Channel initiator with the Fiber Channel World Wide Node Name 0x1234567812345678. A new registration key, 0x12345678, will be registered for the initiator -with the Fibre Channel World Wide Node Name 0x1234567812345678, and the -current initiator will be unregistered from the target. +with the Fibre Channel World Wide Node Name 0x1234567812345678, +and the current initiator will be unregistered from the target. The reservation will be moved to relative target port 2 on the target device. -The registration will persist across power losses. +The registration will persist across power losses: .Bd -literal -offset indent -camcontrol attrib sa0 -v -i attr_values -p 1 +camcontrol persist da0 -v -o register_move -k 0x87654321 \e + -K 0x12345678 -U -p -R 2 -I fcp,0x1234567812345678 .Ed .Pp -This will read and decode the attribute values from partition 1 on the tape -in tape drive sa0, and will display any -.Tn SCSI -errors that result. -.Bd -literal -offset indent -camcontrol zone da0 -v -c rz -P summary -.Ed +Read and decode the attribute values from partition 1 on the tape +in tape drive sa0, and will display any SCSI errors that result: .Pp -This will request the SMR zone list from disk da0, and print out a -summary of the zone parameters, and display any -.Tn SCSI -or -.Tn ATA -errors that result. -.Bd -literal -offset indent -camcontrol zone da0 -v -c rz -o reset -.Ed +.Dl camcontrol attrib sa0 -v -i attr_values -p 1 .Pp -This will request the list of SMR zones that should have their write -pointer reset from the disk da0, and display any -.Tn SCSI -or -.Tn ATA -errors that result. -.Bd -literal -offset indent -camcontrol zone da0 -v -c rwp -l 0x2c80000 -.Ed +Request the SMR zone list from disk da0, and print out a summary +of the zone parameters, and display any SCSI or ATA errors that result: .Pp -This will issue the Reset Write Pointer command to disk da0 for the zone -that starts at LBA 0x2c80000 and display any -.Tn SCSI -or -.Tn ATA -errors that result. -.Bd -literal -offset indent -camcontrol epc ada0 -c timer -T 60.1 -p Idle_a -e -s -.Ed +.Dl camcontrol zone da0 -v -c rz -P summary .Pp -Set the timer for the Idle_a power condition on drive -.Pa ada0 -to 60.1 seconds, enable that particular power condition, and save the timer -value and the enabled state of the power condition. -.Bd -literal -offset indent -camcontrol epc da4 -c goto -p Standby_z -H -.Ed +Request the list of SMR zones that should have their write pointer reset +from the disk da0, and display any SCSI or ATA errors that result: +.Pp +.Dl camcontrol zone da0 -v -c rz -o reset +.Pp +Issue the Reset Write Pointer command to disk da0 for the zone that +starts at LBA 0x2c80000 and display any SCSI or ATA errors that result: +.Pp +.Dl camcontrol zone da0 -v -c rwp -l 0x2c80000 +.Pp +Set the timer for the Idle_a power condition on drive ada0 to +60.1 seconds, enable that particular power condition, +and save the timer value and the enabled state of the power condition: +.Pp +.Dl camcontrol epc ada0 -c timer -T 60.1 -p Idle_a -e -s .Pp -Tell drive -.Pa da4 -to go to the Standby_z power state (which is -the drive's lowest power state) and hold in that state until it is -explicitly released by another +Tell drive da4 to go to the Standby_z power state +.Pq the drive's lowest power state +and hold in that state until it is explicitly released by another .Cm goto -command. -.Bd -literal -offset indent -camcontrol epc da2 -c status -P -.Ed +command: +.Pp +.Dl camcontrol epc da4 -c goto -p Standby_z -H .Pp -Report only the power state of -drive -.Pa da2 . +Report only the power state of drive da2. Some drives will power up in response to the commands sent by the .Pa status subcommand, and the .Fl P option causes .Nm -to only send the -.Tn ATA -CHECK POWER MODE command, which should not trigger a change in the drive's -power state. -.Bd -literal -offset indent -camcontrol epc ada0 -c list -.Ed +to only send the ATA CHECK POWER MODE command, +which should not trigger a change in the drive's power state: +.Pp +.Dl camcontrol epc da2 -c status -P .Pp -Display the ATA Power Conditions log (Log Address 0x08) for -drive -.Pa ada0 . +Display the ATA Power Conditions log (Log Address 0x08) for drive ada0: +.Pp +.Dl camcontrol epc ada0 -c list +.Pp +Set the timestamp of drive sa0 using a +.Xr strptime 3 +format string followed by a time string +that was created using this format string: .Bd -literal -offset indent camcontrol timestamp sa0 -s -f "%a, %d %b %Y %T %z" \e -T "Wed, 26 Oct 2016 21:43:57 -0600" .Ed -.Pp -Set the timestamp of drive -.Pa sa0 -using a -.Xr strptime 3 -format string followed by a time string -that was created using this format string. .Sh SEE ALSO .Xr cam 3 , .Xr cam_cdbparse 3 ,