aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation/scsi
diff options
context:
space:
mode:
authorJeff Garzik <jeff@garzik.org>2006-09-24 01:52:47 -0400
committerJeff Garzik <jeff@garzik.org>2006-09-24 01:52:47 -0400
commit23930fa1cebfea6f79881c588ccd1b0781e49e3f (patch)
tree36d29e3f83661c4f5f45b6f74ac0d5f9886867a8 /Documentation/scsi
parent36b35a5be0e4b406acd816e2122d153e875105be (diff)
parent4f5537de7c1531398e84e18a24f667e49cc94208 (diff)
Merge branch 'master' into upstream
Diffstat (limited to 'Documentation/scsi')
-rw-r--r--Documentation/scsi/ChangeLog.arcmsr56
-rw-r--r--Documentation/scsi/aacraid.txt53
-rw-r--r--Documentation/scsi/arcmsr_spec.txt574
-rw-r--r--Documentation/scsi/libsas.txt484
4 files changed, 1144 insertions, 23 deletions
diff --git a/Documentation/scsi/ChangeLog.arcmsr b/Documentation/scsi/ChangeLog.arcmsr
new file mode 100644
index 000000000000..162c47fdf45f
--- /dev/null
+++ b/Documentation/scsi/ChangeLog.arcmsr
@@ -0,0 +1,56 @@
1**************************************************************************
2** History
3**
4** REV# DATE NAME DESCRIPTION
5** 1.00.00.00 3/31/2004 Erich Chen First release
6** 1.10.00.04 7/28/2004 Erich Chen modify for ioctl
7** 1.10.00.06 8/28/2004 Erich Chen modify for 2.6.x
8** 1.10.00.08 9/28/2004 Erich Chen modify for x86_64
9** 1.10.00.10 10/10/2004 Erich Chen bug fix for SMP & ioctl
10** 1.20.00.00 11/29/2004 Erich Chen bug fix with arcmsr_bus_reset when PHY error
11** 1.20.00.02 12/09/2004 Erich Chen bug fix with over 2T bytes RAID Volume
12** 1.20.00.04 1/09/2005 Erich Chen fits for Debian linux kernel version 2.2.xx
13** 1.20.00.05 2/20/2005 Erich Chen cleanly as look like a Linux driver at 2.6.x
14** thanks for peoples kindness comment
15** Kornel Wieliczek
16** Christoph Hellwig
17** Adrian Bunk
18** Andrew Morton
19** Christoph Hellwig
20** James Bottomley
21** Arjan van de Ven
22** 1.20.00.06 3/12/2005 Erich Chen fix with arcmsr_pci_unmap_dma "unsigned long" cast,
23** modify PCCB POOL allocated by "dma_alloc_coherent"
24** (Kornel Wieliczek's comment)
25** 1.20.00.07 3/23/2005 Erich Chen bug fix with arcmsr_scsi_host_template_init
26** occur segmentation fault,
27** if RAID adapter does not on PCI slot
28** and modprobe/rmmod this driver twice.
29** bug fix enormous stack usage (Adrian Bunk's comment)
30** 1.20.00.08 6/23/2005 Erich Chen bug fix with abort command,
31** in case of heavy loading when sata cable
32** working on low quality connection
33** 1.20.00.09 9/12/2005 Erich Chen bug fix with abort command handling, firmware version check
34** and firmware update notify for hardware bug fix
35** 1.20.00.10 9/23/2005 Erich Chen enhance sysfs function for change driver's max tag Q number.
36** add DMA_64BIT_MASK for backward compatible with all 2.6.x
37** add some useful message for abort command
38** add ioctl code 'ARCMSR_IOCTL_FLUSH_ADAPTER_CACHE'
39** customer can send this command for sync raid volume data
40** 1.20.00.11 9/29/2005 Erich Chen by comment of Arjan van de Ven fix incorrect msleep redefine
41** cast off sizeof(dma_addr_t) condition for 64bit pci_set_dma_mask
42** 1.20.00.12 9/30/2005 Erich Chen bug fix with 64bit platform's ccbs using if over 4G system memory
43** change 64bit pci_set_consistent_dma_mask into 32bit
44** increcct adapter count if adapter initialize fail.
45** miss edit at arcmsr_build_ccb....
46** psge += sizeof(struct _SG64ENTRY *) =>
47** psge += sizeof(struct _SG64ENTRY)
48** 64 bits sg entry would be incorrectly calculated
49** thanks Kornel Wieliczek give me kindly notify
50** and detail description
51** 1.20.00.13 11/15/2005 Erich Chen scheduling pending ccb with FIFO
52** change the architecture of arcmsr command queue list
53** for linux standard list
54** enable usage of pci message signal interrupt
55** follow Randy.Danlup kindness suggestion cleanup this code
56************************************************************************** \ No newline at end of file
diff --git a/Documentation/scsi/aacraid.txt b/Documentation/scsi/aacraid.txt
index be55670851a4..ee03678c8029 100644
--- a/Documentation/scsi/aacraid.txt
+++ b/Documentation/scsi/aacraid.txt
@@ -11,38 +11,43 @@ the original).
11Supported Cards/Chipsets 11Supported Cards/Chipsets
12------------------------- 12-------------------------
13 PCI ID (pci.ids) OEM Product 13 PCI ID (pci.ids) OEM Product
14 9005:0285:9005:028a Adaptec 2020ZCR (Skyhawk) 14 9005:0283:9005:0283 Adaptec Catapult (3210S with arc firmware)
15 9005:0285:9005:028e Adaptec 2020SA (Skyhawk) 15 9005:0284:9005:0284 Adaptec Tomcat (3410S with arc firmware)
16 9005:0285:9005:028b Adaptec 2025ZCR (Terminator)
17 9005:0285:9005:028f Adaptec 2025SA (Terminator)
18 9005:0285:9005:0286 Adaptec 2120S (Crusader)
19 9005:0286:9005:028d Adaptec 2130S (Lancer)
20 9005:0285:9005:0285 Adaptec 2200S (Vulcan) 16 9005:0285:9005:0285 Adaptec 2200S (Vulcan)
17 9005:0285:9005:0286 Adaptec 2120S (Crusader)
21 9005:0285:9005:0287 Adaptec 2200S (Vulcan-2m) 18 9005:0285:9005:0287 Adaptec 2200S (Vulcan-2m)
19 9005:0285:9005:0288 Adaptec 3230S (Harrier)
20 9005:0285:9005:0289 Adaptec 3240S (Tornado)
21 9005:0285:9005:028a Adaptec 2020ZCR (Skyhawk)
22 9005:0285:9005:028b Adaptec 2025ZCR (Terminator)
22 9005:0286:9005:028c Adaptec 2230S (Lancer) 23 9005:0286:9005:028c Adaptec 2230S (Lancer)
23 9005:0286:9005:028c Adaptec 2230SLP (Lancer) 24 9005:0286:9005:028c Adaptec 2230SLP (Lancer)
24 9005:0285:9005:0296 Adaptec 2240S (SabreExpress) 25 9005:0286:9005:028d Adaptec 2130S (Lancer)
26 9005:0285:9005:028e Adaptec 2020SA (Skyhawk)
27 9005:0285:9005:028f Adaptec 2025SA (Terminator)
25 9005:0285:9005:0290 Adaptec 2410SA (Jaguar) 28 9005:0285:9005:0290 Adaptec 2410SA (Jaguar)
26 9005:0285:9005:0293 Adaptec 21610SA (Corsair-16)
27 9005:0285:103c:3227 Adaptec 2610SA (Bearcat HP release) 29 9005:0285:103c:3227 Adaptec 2610SA (Bearcat HP release)
30 9005:0285:9005:0293 Adaptec 21610SA (Corsair-16)
31 9005:0285:9005:0296 Adaptec 2240S (SabreExpress)
28 9005:0285:9005:0292 Adaptec 2810SA (Corsair-8) 32 9005:0285:9005:0292 Adaptec 2810SA (Corsair-8)
29 9005:0285:9005:0294 Adaptec Prowler 33 9005:0285:9005:0294 Adaptec Prowler
30 9005:0286:9005:029d Adaptec 2420SA (Intruder HP release)
31 9005:0286:9005:029c Adaptec 2620SA (Intruder)
32 9005:0286:9005:029b Adaptec 2820SA (Intruder)
33 9005:0286:9005:02a7 Adaptec 2830SA (Skyray)
34 9005:0286:9005:02a8 Adaptec 2430SA (Skyray)
35 9005:0285:9005:0288 Adaptec 3230S (Harrier)
36 9005:0285:9005:0289 Adaptec 3240S (Tornado)
37 9005:0285:9005:0298 Adaptec 4000SAS (BlackBird)
38 9005:0285:9005:0297 Adaptec 4005SAS (AvonPark) 34 9005:0285:9005:0297 Adaptec 4005SAS (AvonPark)
35 9005:0285:9005:0298 Adaptec 4000SAS (BlackBird)
39 9005:0285:9005:0299 Adaptec 4800SAS (Marauder-X) 36 9005:0285:9005:0299 Adaptec 4800SAS (Marauder-X)
40 9005:0285:9005:029a Adaptec 4805SAS (Marauder-E) 37 9005:0285:9005:029a Adaptec 4805SAS (Marauder-E)
38 9005:0286:9005:029b Adaptec 2820SA (Intruder)
39 9005:0286:9005:029c Adaptec 2620SA (Intruder)
40 9005:0286:9005:029d Adaptec 2420SA (Intruder HP release)
41 9005:0286:9005:02a2 Adaptec 3800SAS (Hurricane44) 41 9005:0286:9005:02a2 Adaptec 3800SAS (Hurricane44)
42 9005:0286:9005:02a7 Adaptec 3805SAS (Hurricane80)
43 9005:0286:9005:02a8 Adaptec 3400SAS (Hurricane40)
44 9005:0286:9005:02ac Adaptec 1800SAS (Typhoon44)
45 9005:0286:9005:02b3 Adaptec 2400SAS (Hurricane40lm)
46 9005:0285:9005:02b5 Adaptec ASR5800 (Voodoo44)
47 9005:0285:9005:02b6 Adaptec ASR5805 (Voodoo80)
48 9005:0285:9005:02b7 Adaptec ASR5808 (Voodoo08)
42 1011:0046:9005:0364 Adaptec 5400S (Mustang) 49 1011:0046:9005:0364 Adaptec 5400S (Mustang)
43 1011:0046:9005:0365 Adaptec 5400S (Mustang) 50 1011:0046:9005:0365 Adaptec 5400S (Mustang)
44 9005:0283:9005:0283 Adaptec Catapult (3210S with arc firmware)
45 9005:0284:9005:0284 Adaptec Tomcat (3410S with arc firmware)
46 9005:0287:9005:0800 Adaptec Themisto (Jupiter) 51 9005:0287:9005:0800 Adaptec Themisto (Jupiter)
47 9005:0200:9005:0200 Adaptec Themisto (Jupiter) 52 9005:0200:9005:0200 Adaptec Themisto (Jupiter)
48 9005:0286:9005:0800 Adaptec Callisto (Jupiter) 53 9005:0286:9005:0800 Adaptec Callisto (Jupiter)
@@ -64,18 +69,20 @@ Supported Cards/Chipsets
64 9005:0285:9005:0290 IBM ServeRAID 7t (Jaguar) 69 9005:0285:9005:0290 IBM ServeRAID 7t (Jaguar)
65 9005:0285:1014:02F2 IBM ServeRAID 8i (AvonPark) 70 9005:0285:1014:02F2 IBM ServeRAID 8i (AvonPark)
66 9005:0285:1014:0312 IBM ServeRAID 8i (AvonParkLite) 71 9005:0285:1014:0312 IBM ServeRAID 8i (AvonParkLite)
67 9005:0286:1014:9580 IBM ServeRAID 8k/8k-l8 (Aurora)
68 9005:0286:1014:9540 IBM ServeRAID 8k/8k-l4 (AuroraLite) 72 9005:0286:1014:9540 IBM ServeRAID 8k/8k-l4 (AuroraLite)
69 9005:0286:9005:029f ICP ICP9014R0 (Lancer) 73 9005:0286:1014:9580 IBM ServeRAID 8k/8k-l8 (Aurora)
74 9005:0286:1014:034d IBM ServeRAID 8s (Hurricane)
70 9005:0286:9005:029e ICP ICP9024R0 (Lancer) 75 9005:0286:9005:029e ICP ICP9024R0 (Lancer)
76 9005:0286:9005:029f ICP ICP9014R0 (Lancer)
71 9005:0286:9005:02a0 ICP ICP9047MA (Lancer) 77 9005:0286:9005:02a0 ICP ICP9047MA (Lancer)
72 9005:0286:9005:02a1 ICP ICP9087MA (Lancer) 78 9005:0286:9005:02a1 ICP ICP9087MA (Lancer)
79 9005:0286:9005:02a3 ICP ICP5445AU (Hurricane44)
73 9005:0286:9005:02a4 ICP ICP9085LI (Marauder-X) 80 9005:0286:9005:02a4 ICP ICP9085LI (Marauder-X)
74 9005:0286:9005:02a5 ICP ICP5085BR (Marauder-E) 81 9005:0286:9005:02a5 ICP ICP5085BR (Marauder-E)
75 9005:0286:9005:02a3 ICP ICP5445AU (Hurricane44)
76 9005:0286:9005:02a6 ICP ICP9067MA (Intruder-6) 82 9005:0286:9005:02a6 ICP ICP9067MA (Intruder-6)
77 9005:0286:9005:02a9 ICP ICP5087AU (Skyray) 83 9005:0286:9005:02a9 ICP ICP5085AU (Hurricane80)
78 9005:0286:9005:02aa ICP ICP5047AU (Skyray) 84 9005:0286:9005:02aa ICP ICP5045AU (Hurricane40)
85 9005:0286:9005:02b4 ICP ICP5045AL (Hurricane40lm)
79 86
80People 87People
81------------------------- 88-------------------------
diff --git a/Documentation/scsi/arcmsr_spec.txt b/Documentation/scsi/arcmsr_spec.txt
new file mode 100644
index 000000000000..5e0042340fd3
--- /dev/null
+++ b/Documentation/scsi/arcmsr_spec.txt
@@ -0,0 +1,574 @@
1*******************************************************************************
2** ARECA FIRMWARE SPEC
3*******************************************************************************
4** Usage of IOP331 adapter
5** (All In/Out is in IOP331's view)
6** 1. Message 0 --> InitThread message and retrun code
7** 2. Doorbell is used for RS-232 emulation
8** inDoorBell : bit0 -- data in ready
9** (DRIVER DATA WRITE OK)
10** bit1 -- data out has been read
11** (DRIVER DATA READ OK)
12** outDooeBell: bit0 -- data out ready
13** (IOP331 DATA WRITE OK)
14** bit1 -- data in has been read
15** (IOP331 DATA READ OK)
16** 3. Index Memory Usage
17** offset 0xf00 : for RS232 out (request buffer)
18** offset 0xe00 : for RS232 in (scratch buffer)
19** offset 0xa00 : for inbound message code message_rwbuffer
20** (driver send to IOP331)
21** offset 0xa00 : for outbound message code message_rwbuffer
22** (IOP331 send to driver)
23** 4. RS-232 emulation
24** Currently 128 byte buffer is used
25** 1st uint32_t : Data length (1--124)
26** Byte 4--127 : Max 124 bytes of data
27** 5. PostQ
28** All SCSI Command must be sent through postQ:
29** (inbound queue port) Request frame must be 32 bytes aligned
30** #bit27--bit31 => flag for post ccb
31** #bit0--bit26 => real address (bit27--bit31) of post arcmsr_cdb
32** bit31 :
33** 0 : 256 bytes frame
34** 1 : 512 bytes frame
35** bit30 :
36** 0 : normal request
37** 1 : BIOS request
38** bit29 : reserved
39** bit28 : reserved
40** bit27 : reserved
41** ---------------------------------------------------------------------------
42** (outbount queue port) Request reply
43** #bit27--bit31
44** => flag for reply
45** #bit0--bit26
46** => real address (bit27--bit31) of reply arcmsr_cdb
47** bit31 : must be 0 (for this type of reply)
48** bit30 : reserved for BIOS handshake
49** bit29 : reserved
50** bit28 :
51** 0 : no error, ignore AdapStatus/DevStatus/SenseData
52** 1 : Error, error code in AdapStatus/DevStatus/SenseData
53** bit27 : reserved
54** 6. BIOS request
55** All BIOS request is the same with request from PostQ
56** Except :
57** Request frame is sent from configuration space
58** offset: 0x78 : Request Frame (bit30 == 1)
59** offset: 0x18 : writeonly to generate
60** IRQ to IOP331
61** Completion of request:
62** (bit30 == 0, bit28==err flag)
63** 7. Definition of SGL entry (structure)
64** 8. Message1 Out - Diag Status Code (????)
65** 9. Message0 message code :
66** 0x00 : NOP
67** 0x01 : Get Config
68** ->offset 0xa00 :for outbound message code message_rwbuffer
69** (IOP331 send to driver)
70** Signature 0x87974060(4)
71** Request len 0x00000200(4)
72** numbers of queue 0x00000100(4)
73** SDRAM Size 0x00000100(4)-->256 MB
74** IDE Channels 0x00000008(4)
75** vendor 40 bytes char
76** model 8 bytes char
77** FirmVer 16 bytes char
78** Device Map 16 bytes char
79** FirmwareVersion DWORD <== Added for checking of
80** new firmware capability
81** 0x02 : Set Config
82** ->offset 0xa00 :for inbound message code message_rwbuffer
83** (driver send to IOP331)
84** Signature 0x87974063(4)
85** UPPER32 of Request Frame (4)-->Driver Only
86** 0x03 : Reset (Abort all queued Command)
87** 0x04 : Stop Background Activity
88** 0x05 : Flush Cache
89** 0x06 : Start Background Activity
90** (re-start if background is halted)
91** 0x07 : Check If Host Command Pending
92** (Novell May Need This Function)
93** 0x08 : Set controller time
94** ->offset 0xa00 : for inbound message code message_rwbuffer
95** (driver to IOP331)
96** byte 0 : 0xaa <-- signature
97** byte 1 : 0x55 <-- signature
98** byte 2 : year (04)
99** byte 3 : month (1..12)
100** byte 4 : date (1..31)
101** byte 5 : hour (0..23)
102** byte 6 : minute (0..59)
103** byte 7 : second (0..59)
104*******************************************************************************
105*******************************************************************************
106** RS-232 Interface for Areca Raid Controller
107** The low level command interface is exclusive with VT100 terminal
108** --------------------------------------------------------------------
109** 1. Sequence of command execution
110** --------------------------------------------------------------------
111** (A) Header : 3 bytes sequence (0x5E, 0x01, 0x61)
112** (B) Command block : variable length of data including length,
113** command code, data and checksum byte
114** (C) Return data : variable length of data
115** --------------------------------------------------------------------
116** 2. Command block
117** --------------------------------------------------------------------
118** (A) 1st byte : command block length (low byte)
119** (B) 2nd byte : command block length (high byte)
120** note ..command block length shouldn't > 2040 bytes,
121** length excludes these two bytes
122** (C) 3rd byte : command code
123** (D) 4th and following bytes : variable length data bytes
124** depends on command code
125** (E) last byte : checksum byte (sum of 1st byte until last data byte)
126** --------------------------------------------------------------------
127** 3. Command code and associated data
128** --------------------------------------------------------------------
129** The following are command code defined in raid controller Command
130** code 0x10--0x1? are used for system level management,
131** no password checking is needed and should be implemented in separate
132** well controlled utility and not for end user access.
133** Command code 0x20--0x?? always check the password,
134** password must be entered to enable these command.
135** enum
136** {
137** GUI_SET_SERIAL=0x10,
138** GUI_SET_VENDOR,
139** GUI_SET_MODEL,
140** GUI_IDENTIFY,
141** GUI_CHECK_PASSWORD,
142** GUI_LOGOUT,
143** GUI_HTTP,
144** GUI_SET_ETHERNET_ADDR,
145** GUI_SET_LOGO,
146** GUI_POLL_EVENT,
147** GUI_GET_EVENT,
148** GUI_GET_HW_MONITOR,
149** // GUI_QUICK_CREATE=0x20, (function removed)
150** GUI_GET_INFO_R=0x20,
151** GUI_GET_INFO_V,
152** GUI_GET_INFO_P,
153** GUI_GET_INFO_S,
154** GUI_CLEAR_EVENT,
155** GUI_MUTE_BEEPER=0x30,
156** GUI_BEEPER_SETTING,
157** GUI_SET_PASSWORD,
158** GUI_HOST_INTERFACE_MODE,
159** GUI_REBUILD_PRIORITY,
160** GUI_MAX_ATA_MODE,
161** GUI_RESET_CONTROLLER,
162** GUI_COM_PORT_SETTING,
163** GUI_NO_OPERATION,
164** GUI_DHCP_IP,
165** GUI_CREATE_PASS_THROUGH=0x40,
166** GUI_MODIFY_PASS_THROUGH,
167** GUI_DELETE_PASS_THROUGH,
168** GUI_IDENTIFY_DEVICE,
169** GUI_CREATE_RAIDSET=0x50,
170** GUI_DELETE_RAIDSET,
171** GUI_EXPAND_RAIDSET,
172** GUI_ACTIVATE_RAIDSET,
173** GUI_CREATE_HOT_SPARE,
174** GUI_DELETE_HOT_SPARE,
175** GUI_CREATE_VOLUME=0x60,
176** GUI_MODIFY_VOLUME,
177** GUI_DELETE_VOLUME,
178** GUI_START_CHECK_VOLUME,
179** GUI_STOP_CHECK_VOLUME
180** };
181** Command description :
182** GUI_SET_SERIAL : Set the controller serial#
183** byte 0,1 : length
184** byte 2 : command code 0x10
185** byte 3 : password length (should be 0x0f)
186** byte 4-0x13 : should be "ArEcATecHnoLogY"
187** byte 0x14--0x23 : Serial number string (must be 16 bytes)
188** GUI_SET_VENDOR : Set vendor string for the controller
189** byte 0,1 : length
190** byte 2 : command code 0x11
191** byte 3 : password length (should be 0x08)
192** byte 4-0x13 : should be "ArEcAvAr"
193** byte 0x14--0x3B : vendor string (must be 40 bytes)
194** GUI_SET_MODEL : Set the model name of the controller
195** byte 0,1 : length
196** byte 2 : command code 0x12
197** byte 3 : password length (should be 0x08)
198** byte 4-0x13 : should be "ArEcAvAr"
199** byte 0x14--0x1B : model string (must be 8 bytes)
200** GUI_IDENTIFY : Identify device
201** byte 0,1 : length
202** byte 2 : command code 0x13
203** return "Areca RAID Subsystem "
204** GUI_CHECK_PASSWORD : Verify password
205** byte 0,1 : length
206** byte 2 : command code 0x14
207** byte 3 : password length
208** byte 4-0x?? : user password to be checked
209** GUI_LOGOUT : Logout GUI (force password checking on next command)
210** byte 0,1 : length
211** byte 2 : command code 0x15
212** GUI_HTTP : HTTP interface (reserved for Http proxy service)(0x16)
213**
214** GUI_SET_ETHERNET_ADDR : Set the ethernet MAC address
215** byte 0,1 : length
216** byte 2 : command code 0x17
217** byte 3 : password length (should be 0x08)
218** byte 4-0x13 : should be "ArEcAvAr"
219** byte 0x14--0x19 : Ethernet MAC address (must be 6 bytes)
220** GUI_SET_LOGO : Set logo in HTTP
221** byte 0,1 : length
222** byte 2 : command code 0x18
223** byte 3 : Page# (0/1/2/3) (0xff --> clear OEM logo)
224** byte 4/5/6/7 : 0x55/0xaa/0xa5/0x5a
225** byte 8 : TITLE.JPG data (each page must be 2000 bytes)
226** note page0 1st 2 byte must be
227** actual length of the JPG file
228** GUI_POLL_EVENT : Poll If Event Log Changed
229** byte 0,1 : length
230** byte 2 : command code 0x19
231** GUI_GET_EVENT : Read Event
232** byte 0,1 : length
233** byte 2 : command code 0x1a
234** byte 3 : Event Page (0:1st page/1/2/3:last page)
235** GUI_GET_HW_MONITOR : Get HW monitor data
236** byte 0,1 : length
237** byte 2 : command code 0x1b
238** byte 3 : # of FANs(example 2)
239** byte 4 : # of Voltage sensor(example 3)
240** byte 5 : # of temperature sensor(example 2)
241** byte 6 : # of power
242** byte 7/8 : Fan#0 (RPM)
243** byte 9/10 : Fan#1
244** byte 11/12 : Voltage#0 original value in *1000
245** byte 13/14 : Voltage#0 value
246** byte 15/16 : Voltage#1 org
247** byte 17/18 : Voltage#1
248** byte 19/20 : Voltage#2 org
249** byte 21/22 : Voltage#2
250** byte 23 : Temp#0
251** byte 24 : Temp#1
252** byte 25 : Power indicator (bit0 : power#0,
253** bit1 : power#1)
254** byte 26 : UPS indicator
255** GUI_QUICK_CREATE : Quick create raid/volume set
256** byte 0,1 : length
257** byte 2 : command code 0x20
258** byte 3/4/5/6 : raw capacity
259** byte 7 : raid level
260** byte 8 : stripe size
261** byte 9 : spare
262** byte 10/11/12/13: device mask (the devices to create raid/volume)
263** This function is removed, application like
264** to implement quick create function
265** need to use GUI_CREATE_RAIDSET and GUI_CREATE_VOLUMESET function.
266** GUI_GET_INFO_R : Get Raid Set Information
267** byte 0,1 : length
268** byte 2 : command code 0x20
269** byte 3 : raidset#
270** typedef struct sGUI_RAIDSET
271** {
272** BYTE grsRaidSetName[16];
273** DWORD grsCapacity;
274** DWORD grsCapacityX;
275** DWORD grsFailMask;
276** BYTE grsDevArray[32];
277** BYTE grsMemberDevices;
278** BYTE grsNewMemberDevices;
279** BYTE grsRaidState;
280** BYTE grsVolumes;
281** BYTE grsVolumeList[16];
282** BYTE grsRes1;
283** BYTE grsRes2;
284** BYTE grsRes3;
285** BYTE grsFreeSegments;
286** DWORD grsRawStripes[8];
287** DWORD grsRes4;
288** DWORD grsRes5; // Total to 128 bytes
289** DWORD grsRes6; // Total to 128 bytes
290** } sGUI_RAIDSET, *pGUI_RAIDSET;
291** GUI_GET_INFO_V : Get Volume Set Information
292** byte 0,1 : length
293** byte 2 : command code 0x21
294** byte 3 : volumeset#
295** typedef struct sGUI_VOLUMESET
296** {
297** BYTE gvsVolumeName[16]; // 16
298** DWORD gvsCapacity;
299** DWORD gvsCapacityX;
300** DWORD gvsFailMask;
301** DWORD gvsStripeSize;
302** DWORD gvsNewFailMask;
303** DWORD gvsNewStripeSize;
304** DWORD gvsVolumeStatus;
305** DWORD gvsProgress; // 32
306** sSCSI_ATTR gvsScsi;
307** BYTE gvsMemberDisks;
308** BYTE gvsRaidLevel; // 8
309** BYTE gvsNewMemberDisks;
310** BYTE gvsNewRaidLevel;
311** BYTE gvsRaidSetNumber;
312** BYTE gvsRes0; // 4
313** BYTE gvsRes1[4]; // 64 bytes
314** } sGUI_VOLUMESET, *pGUI_VOLUMESET;
315** GUI_GET_INFO_P : Get Physical Drive Information
316** byte 0,1 : length
317** byte 2 : command code 0x22
318** byte 3 : drive # (from 0 to max-channels - 1)
319** typedef struct sGUI_PHY_DRV
320** {
321** BYTE gpdModelName[40];
322** BYTE gpdSerialNumber[20];
323** BYTE gpdFirmRev[8];
324** DWORD gpdCapacity;
325** DWORD gpdCapacityX; // Reserved for expansion
326** BYTE gpdDeviceState;
327** BYTE gpdPioMode;
328** BYTE gpdCurrentUdmaMode;
329** BYTE gpdUdmaMode;
330** BYTE gpdDriveSelect;
331** BYTE gpdRaidNumber; // 0xff if not belongs to a raid set
332** sSCSI_ATTR gpdScsi;
333** BYTE gpdReserved[40]; // Total to 128 bytes
334** } sGUI_PHY_DRV, *pGUI_PHY_DRV;
335** GUI_GET_INFO_S : Get System Information
336** byte 0,1 : length
337** byte 2 : command code 0x23
338** typedef struct sCOM_ATTR
339** {
340** BYTE comBaudRate;
341** BYTE comDataBits;
342** BYTE comStopBits;
343** BYTE comParity;
344** BYTE comFlowControl;
345** } sCOM_ATTR, *pCOM_ATTR;
346** typedef struct sSYSTEM_INFO
347** {
348** BYTE gsiVendorName[40];
349** BYTE gsiSerialNumber[16];
350** BYTE gsiFirmVersion[16];
351** BYTE gsiBootVersion[16];
352** BYTE gsiMbVersion[16];
353** BYTE gsiModelName[8];
354** BYTE gsiLocalIp[4];
355** BYTE gsiCurrentIp[4];
356** DWORD gsiTimeTick;
357** DWORD gsiCpuSpeed;
358** DWORD gsiICache;
359** DWORD gsiDCache;
360** DWORD gsiScache;
361** DWORD gsiMemorySize;
362** DWORD gsiMemorySpeed;
363** DWORD gsiEvents;
364** BYTE gsiMacAddress[6];
365** BYTE gsiDhcp;
366** BYTE gsiBeeper;
367** BYTE gsiChannelUsage;
368** BYTE gsiMaxAtaMode;
369** BYTE gsiSdramEcc; // 1:if ECC enabled
370** BYTE gsiRebuildPriority;
371** sCOM_ATTR gsiComA; // 5 bytes
372** sCOM_ATTR gsiComB; // 5 bytes
373** BYTE gsiIdeChannels;
374** BYTE gsiScsiHostChannels;
375** BYTE gsiIdeHostChannels;
376** BYTE gsiMaxVolumeSet;
377** BYTE gsiMaxRaidSet;
378** BYTE gsiEtherPort; // 1:if ether net port supported
379** BYTE gsiRaid6Engine; // 1:Raid6 engine supported
380** BYTE gsiRes[75];
381** } sSYSTEM_INFO, *pSYSTEM_INFO;
382** GUI_CLEAR_EVENT : Clear System Event
383** byte 0,1 : length
384** byte 2 : command code 0x24
385** GUI_MUTE_BEEPER : Mute current beeper
386** byte 0,1 : length
387** byte 2 : command code 0x30
388** GUI_BEEPER_SETTING : Disable beeper
389** byte 0,1 : length
390** byte 2 : command code 0x31
391** byte 3 : 0->disable, 1->enable
392** GUI_SET_PASSWORD : Change password
393** byte 0,1 : length
394** byte 2 : command code 0x32
395** byte 3 : pass word length ( must <= 15 )
396** byte 4 : password (must be alpha-numerical)
397** GUI_HOST_INTERFACE_MODE : Set host interface mode
398** byte 0,1 : length
399** byte 2 : command code 0x33
400** byte 3 : 0->Independent, 1->cluster
401** GUI_REBUILD_PRIORITY : Set rebuild priority
402** byte 0,1 : length
403** byte 2 : command code 0x34
404** byte 3 : 0/1/2/3 (low->high)
405** GUI_MAX_ATA_MODE : Set maximum ATA mode to be used
406** byte 0,1 : length
407** byte 2 : command code 0x35
408** byte 3 : 0/1/2/3 (133/100/66/33)
409** GUI_RESET_CONTROLLER : Reset Controller
410** byte 0,1 : length
411** byte 2 : command code 0x36
412** *Response with VT100 screen (discard it)
413** GUI_COM_PORT_SETTING : COM port setting
414** byte 0,1 : length
415** byte 2 : command code 0x37
416** byte 3 : 0->COMA (term port),
417** 1->COMB (debug port)
418** byte 4 : 0/1/2/3/4/5/6/7
419** (1200/2400/4800/9600/19200/38400/57600/115200)
420** byte 5 : data bit
421** (0:7 bit, 1:8 bit : must be 8 bit)
422** byte 6 : stop bit (0:1, 1:2 stop bits)
423** byte 7 : parity (0:none, 1:off, 2:even)
424** byte 8 : flow control
425** (0:none, 1:xon/xoff, 2:hardware => must use none)
426** GUI_NO_OPERATION : No operation
427** byte 0,1 : length
428** byte 2 : command code 0x38
429** GUI_DHCP_IP : Set DHCP option and local IP address
430** byte 0,1 : length
431** byte 2 : command code 0x39
432** byte 3 : 0:dhcp disabled, 1:dhcp enabled
433** byte 4/5/6/7 : IP address
434** GUI_CREATE_PASS_THROUGH : Create pass through disk
435** byte 0,1 : length
436** byte 2 : command code 0x40
437** byte 3 : device #
438** byte 4 : scsi channel (0/1)
439** byte 5 : scsi id (0-->15)
440** byte 6 : scsi lun (0-->7)
441** byte 7 : tagged queue (1 : enabled)
442** byte 8 : cache mode (1 : enabled)
443** byte 9 : max speed (0/1/2/3/4,
444** async/20/40/80/160 for scsi)
445** (0/1/2/3/4, 33/66/100/133/150 for ide )
446** GUI_MODIFY_PASS_THROUGH : Modify pass through disk
447** byte 0,1 : length
448** byte 2 : command code 0x41
449** byte 3 : device #
450** byte 4 : scsi channel (0/1)
451** byte 5 : scsi id (0-->15)
452** byte 6 : scsi lun (0-->7)
453** byte 7 : tagged queue (1 : enabled)
454** byte 8 : cache mode (1 : enabled)
455** byte 9 : max speed (0/1/2/3/4,
456** async/20/40/80/160 for scsi)
457** (0/1/2/3/4, 33/66/100/133/150 for ide )
458** GUI_DELETE_PASS_THROUGH : Delete pass through disk
459** byte 0,1 : length
460** byte 2 : command code 0x42
461** byte 3 : device# to be deleted
462** GUI_IDENTIFY_DEVICE : Identify Device
463** byte 0,1 : length
464** byte 2 : command code 0x43
465** byte 3 : Flash Method
466** (0:flash selected, 1:flash not selected)
467** byte 4/5/6/7 : IDE device mask to be flashed
468** note .... no response data available
469** GUI_CREATE_RAIDSET : Create Raid Set
470** byte 0,1 : length
471** byte 2 : command code 0x50
472** byte 3/4/5/6 : device mask
473** byte 7-22 : raidset name (if byte 7 == 0:use default)
474** GUI_DELETE_RAIDSET : Delete Raid Set
475** byte 0,1 : length
476** byte 2 : command code 0x51
477** byte 3 : raidset#
478** GUI_EXPAND_RAIDSET : Expand Raid Set
479** byte 0,1 : length
480** byte 2 : command code 0x52
481** byte 3 : raidset#
482** byte 4/5/6/7 : device mask for expansion
483** byte 8/9/10 : (8:0 no change, 1 change, 0xff:terminate,
484** 9:new raid level,
485** 10:new stripe size
486** 0/1/2/3/4/5->4/8/16/32/64/128K )
487** byte 11/12/13 : repeat for each volume in the raidset
488** GUI_ACTIVATE_RAIDSET : Activate incomplete raid set
489** byte 0,1 : length
490** byte 2 : command code 0x53
491** byte 3 : raidset#
492** GUI_CREATE_HOT_SPARE : Create hot spare disk
493** byte 0,1 : length
494** byte 2 : command code 0x54
495** byte 3/4/5/6 : device mask for hot spare creation
496** GUI_DELETE_HOT_SPARE : Delete hot spare disk
497** byte 0,1 : length
498** byte 2 : command code 0x55
499** byte 3/4/5/6 : device mask for hot spare deletion
500** GUI_CREATE_VOLUME : Create volume set
501** byte 0,1 : length
502** byte 2 : command code 0x60
503** byte 3 : raidset#
504** byte 4-19 : volume set name
505** (if byte4 == 0, use default)
506** byte 20-27 : volume capacity (blocks)
507** byte 28 : raid level
508** byte 29 : stripe size
509** (0/1/2/3/4/5->4/8/16/32/64/128K)
510** byte 30 : channel
511** byte 31 : ID
512** byte 32 : LUN
513** byte 33 : 1 enable tag
514** byte 34 : 1 enable cache
515** byte 35 : speed
516** (0/1/2/3/4->async/20/40/80/160 for scsi)
517** (0/1/2/3/4->33/66/100/133/150 for IDE )
518** byte 36 : 1 to select quick init
519**
520** GUI_MODIFY_VOLUME : Modify volume Set
521** byte 0,1 : length
522** byte 2 : command code 0x61
523** byte 3 : volumeset#
524** byte 4-19 : new volume set name
525** (if byte4 == 0, not change)
526** byte 20-27 : new volume capacity (reserved)
527** byte 28 : new raid level
528** byte 29 : new stripe size
529** (0/1/2/3/4/5->4/8/16/32/64/128K)
530** byte 30 : new channel
531** byte 31 : new ID
532** byte 32 : new LUN
533** byte 33 : 1 enable tag
534** byte 34 : 1 enable cache
535** byte 35 : speed
536** (0/1/2/3/4->async/20/40/80/160 for scsi)
537** (0/1/2/3/4->33/66/100/133/150 for IDE )
538** GUI_DELETE_VOLUME : Delete volume set
539** byte 0,1 : length
540** byte 2 : command code 0x62
541** byte 3 : volumeset#
542** GUI_START_CHECK_VOLUME : Start volume consistency check
543** byte 0,1 : length
544** byte 2 : command code 0x63
545** byte 3 : volumeset#
546** GUI_STOP_CHECK_VOLUME : Stop volume consistency check
547** byte 0,1 : length
548** byte 2 : command code 0x64
549** ---------------------------------------------------------------------
550** 4. Returned data
551** ---------------------------------------------------------------------
552** (A) Header : 3 bytes sequence (0x5E, 0x01, 0x61)
553** (B) Length : 2 bytes
554** (low byte 1st, excludes length and checksum byte)
555** (C) status or data :
556** <1> If length == 1 ==> 1 byte status code
557** #define GUI_OK 0x41
558** #define GUI_RAIDSET_NOT_NORMAL 0x42
559** #define GUI_VOLUMESET_NOT_NORMAL 0x43
560** #define GUI_NO_RAIDSET 0x44
561** #define GUI_NO_VOLUMESET 0x45
562** #define GUI_NO_PHYSICAL_DRIVE 0x46
563** #define GUI_PARAMETER_ERROR 0x47
564** #define GUI_UNSUPPORTED_COMMAND 0x48
565** #define GUI_DISK_CONFIG_CHANGED 0x49
566** #define GUI_INVALID_PASSWORD 0x4a
567** #define GUI_NO_DISK_SPACE 0x4b
568** #define GUI_CHECKSUM_ERROR 0x4c
569** #define GUI_PASSWORD_REQUIRED 0x4d
570** <2> If length > 1 ==>
571** data block returned from controller
572** and the contents depends on the command code
573** (E) Checksum : checksum of length and status or data byte
574**************************************************************************
diff --git a/Documentation/scsi/libsas.txt b/Documentation/scsi/libsas.txt
new file mode 100644
index 000000000000..9e2078b2a615
--- /dev/null
+++ b/Documentation/scsi/libsas.txt
@@ -0,0 +1,484 @@
1SAS Layer
2---------
3
4The SAS Layer is a management infrastructure which manages
5SAS LLDDs. It sits between SCSI Core and SAS LLDDs. The
6layout is as follows: while SCSI Core is concerned with
7SAM/SPC issues, and a SAS LLDD+sequencer is concerned with
8phy/OOB/link management, the SAS layer is concerned with:
9
10 * SAS Phy/Port/HA event management (LLDD generates,
11 SAS Layer processes),
12 * SAS Port management (creation/destruction),
13 * SAS Domain discovery and revalidation,
14 * SAS Domain device management,
15 * SCSI Host registration/unregistration,
16 * Device registration with SCSI Core (SAS) or libata
17 (SATA), and
18 * Expander management and exporting expander control
19 to user space.
20
21A SAS LLDD is a PCI device driver. It is concerned with
22phy/OOB management, and vendor specific tasks and generates
23events to the SAS layer.
24
25The SAS Layer does most SAS tasks as outlined in the SAS 1.1
26spec.
27
28The sas_ha_struct describes the SAS LLDD to the SAS layer.
29Most of it is used by the SAS Layer but a few fields need to
30be initialized by the LLDDs.
31
32After initializing your hardware, from the probe() function
33you call sas_register_ha(). It will register your LLDD with
34the SCSI subsystem, creating a SCSI host and it will
35register your SAS driver with the sysfs SAS tree it creates.
36It will then return. Then you enable your phys to actually
37start OOB (at which point your driver will start calling the
38notify_* event callbacks).
39
40Structure descriptions:
41
42struct sas_phy --------------------
43Normally this is statically embedded to your driver's
44phy structure:
45 struct my_phy {
46 blah;
47 struct sas_phy sas_phy;
48 bleh;
49 };
50And then all the phys are an array of my_phy in your HA
51struct (shown below).
52
53Then as you go along and initialize your phys you also
54initialize the sas_phy struct, along with your own
55phy structure.
56
57In general, the phys are managed by the LLDD and the ports
58are managed by the SAS layer. So the phys are initialized
59and updated by the LLDD and the ports are initialized and
60updated by the SAS layer.
61
62There is a scheme where the LLDD can RW certain fields,
63and the SAS layer can only read such ones, and vice versa.
64The idea is to avoid unnecessary locking.
65
66enabled -- must be set (0/1)
67id -- must be set [0,MAX_PHYS)
68class, proto, type, role, oob_mode, linkrate -- must be set
69oob_mode -- you set this when OOB has finished and then notify
70the SAS Layer.
71
72sas_addr -- this normally points to an array holding the sas
73address of the phy, possibly somewhere in your my_phy
74struct.
75
76attached_sas_addr -- set this when you (LLDD) receive an
77IDENTIFY frame or a FIS frame, _before_ notifying the SAS
78layer. The idea is that sometimes the LLDD may want to fake
79or provide a different SAS address on that phy/port and this
80allows it to do this. At best you should copy the sas
81address from the IDENTIFY frame or maybe generate a SAS
82address for SATA directly attached devices. The Discover
83process may later change this.
84
85frame_rcvd -- this is where you copy the IDENTIFY/FIS frame
86when you get it; you lock, copy, set frame_rcvd_size and
87unlock the lock, and then call the event. It is a pointer
88since there's no way to know your hw frame size _exactly_,
89so you define the actual array in your phy struct and let
90this pointer point to it. You copy the frame from your
91DMAable memory to that area holding the lock.
92
93sas_prim -- this is where primitives go when they're
94received. See sas.h. Grab the lock, set the primitive,
95release the lock, notify.
96
97port -- this points to the sas_port if the phy belongs
98to a port -- the LLDD only reads this. It points to the
99sas_port this phy is part of. Set by the SAS Layer.
100
101ha -- may be set; the SAS layer sets it anyway.
102
103lldd_phy -- you should set this to point to your phy so you
104can find your way around faster when the SAS layer calls one
105of your callbacks and passes you a phy. If the sas_phy is
106embedded you can also use container_of -- whatever you
107prefer.
108
109
110struct sas_port --------------------
111The LLDD doesn't set any fields of this struct -- it only
112reads them. They should be self explanatory.
113
114phy_mask is 32 bit, this should be enough for now, as I
115haven't heard of a HA having more than 8 phys.
116
117lldd_port -- I haven't found use for that -- maybe other
118LLDD who wish to have internal port representation can make
119use of this.
120
121
122struct sas_ha_struct --------------------
123It normally is statically declared in your own LLDD
124structure describing your adapter:
125struct my_sas_ha {
126 blah;
127 struct sas_ha_struct sas_ha;
128 struct my_phy phys[MAX_PHYS];
129 struct sas_port sas_ports[MAX_PHYS]; /* (1) */
130 bleh;
131};
132
133(1) If your LLDD doesn't have its own port representation.
134
135What needs to be initialized (sample function given below).
136
137pcidev
138sas_addr -- since the SAS layer doesn't want to mess with
139 memory allocation, etc, this points to statically
140 allocated array somewhere (say in your host adapter
141 structure) and holds the SAS address of the host
142 adapter as given by you or the manufacturer, etc.
143sas_port
144sas_phy -- an array of pointers to structures. (see
145 note above on sas_addr).
146 These must be set. See more notes below.
147num_phys -- the number of phys present in the sas_phy array,
148 and the number of ports present in the sas_port
149 array. There can be a maximum num_phys ports (one per
150 port) so we drop the num_ports, and only use
151 num_phys.
152
153The event interface:
154
155 /* LLDD calls these to notify the class of an event. */
156 void (*notify_ha_event)(struct sas_ha_struct *, enum ha_event);
157 void (*notify_port_event)(struct sas_phy *, enum port_event);
158 void (*notify_phy_event)(struct sas_phy *, enum phy_event);
159
160When sas_register_ha() returns, those are set and can be
161called by the LLDD to notify the SAS layer of such events
162the SAS layer.
163
164The port notification:
165
166 /* The class calls these to notify the LLDD of an event. */
167 void (*lldd_port_formed)(struct sas_phy *);
168 void (*lldd_port_deformed)(struct sas_phy *);
169
170If the LLDD wants notification when a port has been formed
171or deformed it sets those to a function satisfying the type.
172
173A SAS LLDD should also implement at least one of the Task
174Management Functions (TMFs) described in SAM:
175
176 /* Task Management Functions. Must be called from process context. */
177 int (*lldd_abort_task)(struct sas_task *);
178 int (*lldd_abort_task_set)(struct domain_device *, u8 *lun);
179 int (*lldd_clear_aca)(struct domain_device *, u8 *lun);
180 int (*lldd_clear_task_set)(struct domain_device *, u8 *lun);
181 int (*lldd_I_T_nexus_reset)(struct domain_device *);
182 int (*lldd_lu_reset)(struct domain_device *, u8 *lun);
183 int (*lldd_query_task)(struct sas_task *);
184
185For more information please read SAM from T10.org.
186
187Port and Adapter management:
188
189 /* Port and Adapter management */
190 int (*lldd_clear_nexus_port)(struct sas_port *);
191 int (*lldd_clear_nexus_ha)(struct sas_ha_struct *);
192
193A SAS LLDD should implement at least one of those.
194
195Phy management:
196
197 /* Phy management */
198 int (*lldd_control_phy)(struct sas_phy *, enum phy_func);
199
200lldd_ha -- set this to point to your HA struct. You can also
201use container_of if you embedded it as shown above.
202
203A sample initialization and registration function
204can look like this (called last thing from probe())
205*but* before you enable the phys to do OOB:
206
207static int register_sas_ha(struct my_sas_ha *my_ha)
208{
209 int i;
210 static struct sas_phy *sas_phys[MAX_PHYS];
211 static struct sas_port *sas_ports[MAX_PHYS];
212
213 my_ha->sas_ha.sas_addr = &my_ha->sas_addr[0];
214
215 for (i = 0; i < MAX_PHYS; i++) {
216 sas_phys[i] = &my_ha->phys[i].sas_phy;
217 sas_ports[i] = &my_ha->sas_ports[i];
218 }
219
220 my_ha->sas_ha.sas_phy = sas_phys;
221 my_ha->sas_ha.sas_port = sas_ports;
222 my_ha->sas_ha.num_phys = MAX_PHYS;
223
224 my_ha->sas_ha.lldd_port_formed = my_port_formed;
225
226 my_ha->sas_ha.lldd_dev_found = my_dev_found;
227 my_ha->sas_ha.lldd_dev_gone = my_dev_gone;
228
229 my_ha->sas_ha.lldd_max_execute_num = lldd_max_execute_num; (1)
230
231 my_ha->sas_ha.lldd_queue_size = ha_can_queue;
232 my_ha->sas_ha.lldd_execute_task = my_execute_task;
233
234 my_ha->sas_ha.lldd_abort_task = my_abort_task;
235 my_ha->sas_ha.lldd_abort_task_set = my_abort_task_set;
236 my_ha->sas_ha.lldd_clear_aca = my_clear_aca;
237 my_ha->sas_ha.lldd_clear_task_set = my_clear_task_set;
238 my_ha->sas_ha.lldd_I_T_nexus_reset= NULL; (2)
239 my_ha->sas_ha.lldd_lu_reset = my_lu_reset;
240 my_ha->sas_ha.lldd_query_task = my_query_task;
241
242 my_ha->sas_ha.lldd_clear_nexus_port = my_clear_nexus_port;
243 my_ha->sas_ha.lldd_clear_nexus_ha = my_clear_nexus_ha;
244
245 my_ha->sas_ha.lldd_control_phy = my_control_phy;
246
247 return sas_register_ha(&my_ha->sas_ha);
248}
249
250(1) This is normally a LLDD parameter, something of the
251lines of a task collector. What it tells the SAS Layer is
252whether the SAS layer should run in Direct Mode (default:
253value 0 or 1) or Task Collector Mode (value greater than 1).
254
255In Direct Mode, the SAS Layer calls Execute Task as soon as
256it has a command to send to the SDS, _and_ this is a single
257command, i.e. not linked.
258
259Some hardware (e.g. aic94xx) has the capability to DMA more
260than one task at a time (interrupt) from host memory. Task
261Collector Mode is an optional feature for HAs which support
262this in their hardware. (Again, it is completely optional
263even if your hardware supports it.)
264
265In Task Collector Mode, the SAS Layer would do _natural_
266coalescing of tasks and at the appropriate moment it would
267call your driver to DMA more than one task in a single HA
268interrupt. DMBS may want to use this by insmod/modprobe
269setting the lldd_max_execute_num to something greater than
2701.
271
272(2) SAS 1.1 does not define I_T Nexus Reset TMF.
273
274Events
275------
276
277Events are _the only way_ a SAS LLDD notifies the SAS layer
278of anything. There is no other method or way a LLDD to tell
279the SAS layer of anything happening internally or in the SAS
280domain.
281
282Phy events:
283 PHYE_LOSS_OF_SIGNAL, (C)
284 PHYE_OOB_DONE,
285 PHYE_OOB_ERROR, (C)
286 PHYE_SPINUP_HOLD.
287
288Port events, passed on a _phy_:
289 PORTE_BYTES_DMAED, (M)
290 PORTE_BROADCAST_RCVD, (E)
291 PORTE_LINK_RESET_ERR, (C)
292 PORTE_TIMER_EVENT, (C)
293 PORTE_HARD_RESET.
294
295Host Adapter event:
296 HAE_RESET
297
298A SAS LLDD should be able to generate
299 - at least one event from group C (choice),
300 - events marked M (mandatory) are mandatory (only one),
301 - events marked E (expander) if it wants the SAS layer
302 to handle domain revalidation (only one such).
303 - Unmarked events are optional.
304
305Meaning:
306
307HAE_RESET -- when your HA got internal error and was reset.
308
309PORTE_BYTES_DMAED -- on receiving an IDENTIFY/FIS frame
310PORTE_BROADCAST_RCVD -- on receiving a primitive
311PORTE_LINK_RESET_ERR -- timer expired, loss of signal, loss
312of DWS, etc. (*)
313PORTE_TIMER_EVENT -- DWS reset timeout timer expired (*)
314PORTE_HARD_RESET -- Hard Reset primitive received.
315
316PHYE_LOSS_OF_SIGNAL -- the device is gone (*)
317PHYE_OOB_DONE -- OOB went fine and oob_mode is valid
318PHYE_OOB_ERROR -- Error while doing OOB, the device probably
319got disconnected. (*)
320PHYE_SPINUP_HOLD -- SATA is present, COMWAKE not sent.
321
322(*) should set/clear the appropriate fields in the phy,
323 or alternatively call the inlined sas_phy_disconnected()
324 which is just a helper, from their tasklet.
325
326The Execute Command SCSI RPC:
327
328 int (*lldd_execute_task)(struct sas_task *, int num,
329 unsigned long gfp_flags);
330
331Used to queue a task to the SAS LLDD. @task is the tasks to
332be executed. @num should be the number of tasks being
333queued at this function call (they are linked listed via
334task::list), @gfp_mask should be the gfp_mask defining the
335context of the caller.
336
337This function should implement the Execute Command SCSI RPC,
338or if you're sending a SCSI Task as linked commands, you
339should also use this function.
340
341That is, when lldd_execute_task() is called, the command(s)
342go out on the transport *immediately*. There is *no*
343queuing of any sort and at any level in a SAS LLDD.
344
345The use of task::list is two-fold, one for linked commands,
346the other discussed below.
347
348It is possible to queue up more than one task at a time, by
349initializing the list element of struct sas_task, and
350passing the number of tasks enlisted in this manner in num.
351
352Returns: -SAS_QUEUE_FULL, -ENOMEM, nothing was queued;
353 0, the task(s) were queued.
354
355If you want to pass num > 1, then either
356A) you're the only caller of this function and keep track
357 of what you've queued to the LLDD, or
358B) you know what you're doing and have a strategy of
359 retrying.
360
361As opposed to queuing one task at a time (function call),
362batch queuing of tasks, by having num > 1, greatly
363simplifies LLDD code, sequencer code, and _hardware design_,
364and has some performance advantages in certain situations
365(DBMS).
366
367The LLDD advertises if it can take more than one command at
368a time at lldd_execute_task(), by setting the
369lldd_max_execute_num parameter (controlled by "collector"
370module parameter in aic94xx SAS LLDD).
371
372You should leave this to the default 1, unless you know what
373you're doing.
374
375This is a function of the LLDD, to which the SAS layer can
376cater to.
377
378int lldd_queue_size
379 The host adapter's queue size. This is the maximum
380number of commands the lldd can have pending to domain
381devices on behalf of all upper layers submitting through
382lldd_execute_task().
383
384You really want to set this to something (much) larger than
3851.
386
387This _really_ has absolutely nothing to do with queuing.
388There is no queuing in SAS LLDDs.
389
390struct sas_task {
391 dev -- the device this task is destined to
392 list -- must be initialized (INIT_LIST_HEAD)
393 task_proto -- _one_ of enum sas_proto
394 scatter -- pointer to scatter gather list array
395 num_scatter -- number of elements in scatter
396 total_xfer_len -- total number of bytes expected to be transfered
397 data_dir -- PCI_DMA_...
398 task_done -- callback when the task has finished execution
399};
400
401When an external entity, entity other than the LLDD or the
402SAS Layer, wants to work with a struct domain_device, it
403_must_ call kobject_get() when getting a handle on the
404device and kobject_put() when it is done with the device.
405
406This does two things:
407 A) implements proper kfree() for the device;
408 B) increments/decrements the kref for all players:
409 domain_device
410 all domain_device's ... (if past an expander)
411 port
412 host adapter
413 pci device
414 and up the ladder, etc.
415
416DISCOVERY
417---------
418
419The sysfs tree has the following purposes:
420 a) It shows you the physical layout of the SAS domain at
421 the current time, i.e. how the domain looks in the
422 physical world right now.
423 b) Shows some device parameters _at_discovery_time_.
424
425This is a link to the tree(1) program, very useful in
426viewing the SAS domain:
427ftp://mama.indstate.edu/linux/tree/
428I expect user space applications to actually create a
429graphical interface of this.
430
431That is, the sysfs domain tree doesn't show or keep state if
432you e.g., change the meaning of the READY LED MEANING
433setting, but it does show you the current connection status
434of the domain device.
435
436Keeping internal device state changes is responsibility of
437upper layers (Command set drivers) and user space.
438
439When a device or devices are unplugged from the domain, this
440is reflected in the sysfs tree immediately, and the device(s)
441removed from the system.
442
443The structure domain_device describes any device in the SAS
444domain. It is completely managed by the SAS layer. A task
445points to a domain device, this is how the SAS LLDD knows
446where to send the task(s) to. A SAS LLDD only reads the
447contents of the domain_device structure, but it never creates
448or destroys one.
449
450Expander management from User Space
451-----------------------------------
452
453In each expander directory in sysfs, there is a file called
454"smp_portal". It is a binary sysfs attribute file, which
455implements an SMP portal (Note: this is *NOT* an SMP port),
456to which user space applications can send SMP requests and
457receive SMP responses.
458
459Functionality is deceptively simple:
460
4611. Build the SMP frame you want to send. The format and layout
462 is described in the SAS spec. Leave the CRC field equal 0.
463open(2)
4642. Open the expander's SMP portal sysfs file in RW mode.
465write(2)
4663. Write the frame you built in 1.
467read(2)
4684. Read the amount of data you expect to receive for the frame you built.
469 If you receive different amount of data you expected to receive,
470 then there was some kind of error.
471close(2)
472All this process is shown in detail in the function do_smp_func()
473and its callers, in the file "expander_conf.c".
474
475The kernel functionality is implemented in the file
476"sas_expander.c".
477
478The program "expander_conf.c" implements this. It takes one
479argument, the sysfs file name of the SMP portal to the
480expander, and gives expander information, including routing
481tables.
482
483The SMP portal gives you complete control of the expander,
484so please be careful.
generated by cgit v1.2.2 (git 2.25.0) at 2025-01-01 23:00:14 -0500