diff options
author | Jeff Garzik <jeff@garzik.org> | 2006-09-24 01:52:47 -0400 |
---|---|---|
committer | Jeff Garzik <jeff@garzik.org> | 2006-09-24 01:52:47 -0400 |
commit | 23930fa1cebfea6f79881c588ccd1b0781e49e3f (patch) | |
tree | 36d29e3f83661c4f5f45b6f74ac0d5f9886867a8 /Documentation | |
parent | 36b35a5be0e4b406acd816e2122d153e875105be (diff) | |
parent | 4f5537de7c1531398e84e18a24f667e49cc94208 (diff) |
Merge branch 'master' into upstream
Diffstat (limited to 'Documentation')
-rw-r--r-- | Documentation/00-INDEX | 2 | ||||
-rw-r--r-- | Documentation/crypto/api-intro.txt | 36 | ||||
-rw-r--r-- | Documentation/kernel-parameters.txt | 2 | ||||
-rw-r--r-- | Documentation/netlabel/00-INDEX | 10 | ||||
-rw-r--r-- | Documentation/netlabel/cipso_ipv4.txt | 48 | ||||
-rw-r--r-- | Documentation/netlabel/draft-ietf-cipso-ipsecurity-01.txt | 791 | ||||
-rw-r--r-- | Documentation/netlabel/introduction.txt | 46 | ||||
-rw-r--r-- | Documentation/netlabel/lsm_interface.txt | 47 | ||||
-rw-r--r-- | Documentation/networking/ip-sysctl.txt | 38 | ||||
-rw-r--r-- | Documentation/networking/secid.txt | 14 | ||||
-rw-r--r-- | Documentation/scsi/ChangeLog.arcmsr | 56 | ||||
-rw-r--r-- | Documentation/scsi/aacraid.txt | 53 | ||||
-rw-r--r-- | Documentation/scsi/arcmsr_spec.txt | 574 | ||||
-rw-r--r-- | Documentation/scsi/libsas.txt | 484 | ||||
-rw-r--r-- | Documentation/sound/alsa/ALSA-Configuration.txt | 44 | ||||
-rw-r--r-- | Documentation/sound/alsa/DocBook/writing-an-alsa-driver.tmpl | 5 |
16 files changed, 2203 insertions, 47 deletions
diff --git a/Documentation/00-INDEX b/Documentation/00-INDEX index 5f7f7d7f77d2..02457ec9c94f 100644 --- a/Documentation/00-INDEX +++ b/Documentation/00-INDEX | |||
@@ -184,6 +184,8 @@ mtrr.txt | |||
184 | - how to use PPro Memory Type Range Registers to increase performance. | 184 | - how to use PPro Memory Type Range Registers to increase performance. |
185 | nbd.txt | 185 | nbd.txt |
186 | - info on a TCP implementation of a network block device. | 186 | - info on a TCP implementation of a network block device. |
187 | netlabel/ | ||
188 | - directory with information on the NetLabel subsystem. | ||
187 | networking/ | 189 | networking/ |
188 | - directory with info on various aspects of networking with Linux. | 190 | - directory with info on various aspects of networking with Linux. |
189 | nfsroot.txt | 191 | nfsroot.txt |
diff --git a/Documentation/crypto/api-intro.txt b/Documentation/crypto/api-intro.txt index 74dffc68ff9f..5a03a2801d67 100644 --- a/Documentation/crypto/api-intro.txt +++ b/Documentation/crypto/api-intro.txt | |||
@@ -19,15 +19,14 @@ At the lowest level are algorithms, which register dynamically with the | |||
19 | API. | 19 | API. |
20 | 20 | ||
21 | 'Transforms' are user-instantiated objects, which maintain state, handle all | 21 | 'Transforms' are user-instantiated objects, which maintain state, handle all |
22 | of the implementation logic (e.g. manipulating page vectors), provide an | 22 | of the implementation logic (e.g. manipulating page vectors) and provide an |
23 | abstraction to the underlying algorithms, and handle common logical | 23 | abstraction to the underlying algorithms. However, at the user |
24 | operations (e.g. cipher modes, HMAC for digests). However, at the user | ||
25 | level they are very simple. | 24 | level they are very simple. |
26 | 25 | ||
27 | Conceptually, the API layering looks like this: | 26 | Conceptually, the API layering looks like this: |
28 | 27 | ||
29 | [transform api] (user interface) | 28 | [transform api] (user interface) |
30 | [transform ops] (per-type logic glue e.g. cipher.c, digest.c) | 29 | [transform ops] (per-type logic glue e.g. cipher.c, compress.c) |
31 | [algorithm api] (for registering algorithms) | 30 | [algorithm api] (for registering algorithms) |
32 | 31 | ||
33 | The idea is to make the user interface and algorithm registration API | 32 | The idea is to make the user interface and algorithm registration API |
@@ -44,22 +43,27 @@ under development. | |||
44 | Here's an example of how to use the API: | 43 | Here's an example of how to use the API: |
45 | 44 | ||
46 | #include <linux/crypto.h> | 45 | #include <linux/crypto.h> |
46 | #include <linux/err.h> | ||
47 | #include <linux/scatterlist.h> | ||
47 | 48 | ||
48 | struct scatterlist sg[2]; | 49 | struct scatterlist sg[2]; |
49 | char result[128]; | 50 | char result[128]; |
50 | struct crypto_tfm *tfm; | 51 | struct crypto_hash *tfm; |
52 | struct hash_desc desc; | ||
51 | 53 | ||
52 | tfm = crypto_alloc_tfm("md5", 0); | 54 | tfm = crypto_alloc_hash("md5", 0, CRYPTO_ALG_ASYNC); |
53 | if (tfm == NULL) | 55 | if (IS_ERR(tfm)) |
54 | fail(); | 56 | fail(); |
55 | 57 | ||
56 | /* ... set up the scatterlists ... */ | 58 | /* ... set up the scatterlists ... */ |
59 | |||
60 | desc.tfm = tfm; | ||
61 | desc.flags = 0; | ||
57 | 62 | ||
58 | crypto_digest_init(tfm); | 63 | if (crypto_hash_digest(&desc, &sg, 2, result)) |
59 | crypto_digest_update(tfm, &sg, 2); | 64 | fail(); |
60 | crypto_digest_final(tfm, result); | ||
61 | 65 | ||
62 | crypto_free_tfm(tfm); | 66 | crypto_free_hash(tfm); |
63 | 67 | ||
64 | 68 | ||
65 | Many real examples are available in the regression test module (tcrypt.c). | 69 | Many real examples are available in the regression test module (tcrypt.c). |
@@ -126,7 +130,7 @@ might already be working on. | |||
126 | BUGS | 130 | BUGS |
127 | 131 | ||
128 | Send bug reports to: | 132 | Send bug reports to: |
129 | James Morris <jmorris@redhat.com> | 133 | Herbert Xu <herbert@gondor.apana.org.au> |
130 | Cc: David S. Miller <davem@redhat.com> | 134 | Cc: David S. Miller <davem@redhat.com> |
131 | 135 | ||
132 | 136 | ||
@@ -134,13 +138,14 @@ FURTHER INFORMATION | |||
134 | 138 | ||
135 | For further patches and various updates, including the current TODO | 139 | For further patches and various updates, including the current TODO |
136 | list, see: | 140 | list, see: |
137 | http://samba.org/~jamesm/crypto/ | 141 | http://gondor.apana.org.au/~herbert/crypto/ |
138 | 142 | ||
139 | 143 | ||
140 | AUTHORS | 144 | AUTHORS |
141 | 145 | ||
142 | James Morris | 146 | James Morris |
143 | David S. Miller | 147 | David S. Miller |
148 | Herbert Xu | ||
144 | 149 | ||
145 | 150 | ||
146 | CREDITS | 151 | CREDITS |
@@ -238,8 +243,11 @@ Anubis algorithm contributors: | |||
238 | Tiger algorithm contributors: | 243 | Tiger algorithm contributors: |
239 | Aaron Grothe | 244 | Aaron Grothe |
240 | 245 | ||
246 | VIA PadLock contributors: | ||
247 | Michal Ludvig | ||
248 | |||
241 | Generic scatterwalk code by Adam J. Richter <adam@yggdrasil.com> | 249 | Generic scatterwalk code by Adam J. Richter <adam@yggdrasil.com> |
242 | 250 | ||
243 | Please send any credits updates or corrections to: | 251 | Please send any credits updates or corrections to: |
244 | James Morris <jmorris@redhat.com> | 252 | Herbert Xu <herbert@gondor.apana.org.au> |
245 | 253 | ||
diff --git a/Documentation/kernel-parameters.txt b/Documentation/kernel-parameters.txt index 87a17337c7f6..71d05f481727 100644 --- a/Documentation/kernel-parameters.txt +++ b/Documentation/kernel-parameters.txt | |||
@@ -1189,8 +1189,6 @@ running once the system is up. | |||
1189 | Mechanism 2. | 1189 | Mechanism 2. |
1190 | nommconf [IA-32,X86_64] Disable use of MMCONFIG for PCI | 1190 | nommconf [IA-32,X86_64] Disable use of MMCONFIG for PCI |
1191 | Configuration | 1191 | Configuration |
1192 | mmconf [IA-32,X86_64] Force MMCONFIG. This is useful | ||
1193 | to override the builtin blacklist. | ||
1194 | nomsi [MSI] If the PCI_MSI kernel config parameter is | 1192 | nomsi [MSI] If the PCI_MSI kernel config parameter is |
1195 | enabled, this kernel boot option can be used to | 1193 | enabled, this kernel boot option can be used to |
1196 | disable the use of MSI interrupts system-wide. | 1194 | disable the use of MSI interrupts system-wide. |
diff --git a/Documentation/netlabel/00-INDEX b/Documentation/netlabel/00-INDEX new file mode 100644 index 000000000000..837bf35990e2 --- /dev/null +++ b/Documentation/netlabel/00-INDEX | |||
@@ -0,0 +1,10 @@ | |||
1 | 00-INDEX | ||
2 | - this file. | ||
3 | cipso_ipv4.txt | ||
4 | - documentation on the IPv4 CIPSO protocol engine. | ||
5 | draft-ietf-cipso-ipsecurity-01.txt | ||
6 | - IETF draft of the CIPSO protocol, dated 16 July 1992. | ||
7 | introduction.txt | ||
8 | - NetLabel introduction, READ THIS FIRST. | ||
9 | lsm_interface.txt | ||
10 | - documentation on the NetLabel kernel security module API. | ||
diff --git a/Documentation/netlabel/cipso_ipv4.txt b/Documentation/netlabel/cipso_ipv4.txt new file mode 100644 index 000000000000..93dacb132c3c --- /dev/null +++ b/Documentation/netlabel/cipso_ipv4.txt | |||
@@ -0,0 +1,48 @@ | |||
1 | NetLabel CIPSO/IPv4 Protocol Engine | ||
2 | ============================================================================== | ||
3 | Paul Moore, paul.moore@hp.com | ||
4 | |||
5 | May 17, 2006 | ||
6 | |||
7 | * Overview | ||
8 | |||
9 | The NetLabel CIPSO/IPv4 protocol engine is based on the IETF Commercial IP | ||
10 | Security Option (CIPSO) draft from July 16, 1992. A copy of this draft can be | ||
11 | found in this directory, consult '00-INDEX' for the filename. While the IETF | ||
12 | draft never made it to an RFC standard it has become a de-facto standard for | ||
13 | labeled networking and is used in many trusted operating systems. | ||
14 | |||
15 | * Outbound Packet Processing | ||
16 | |||
17 | The CIPSO/IPv4 protocol engine applies the CIPSO IP option to packets by | ||
18 | adding the CIPSO label to the socket. This causes all packets leaving the | ||
19 | system through the socket to have the CIPSO IP option applied. The socket's | ||
20 | CIPSO label can be changed at any point in time, however, it is recommended | ||
21 | that it is set upon the socket's creation. The LSM can set the socket's CIPSO | ||
22 | label by using the NetLabel security module API; if the NetLabel "domain" is | ||
23 | configured to use CIPSO for packet labeling then a CIPSO IP option will be | ||
24 | generated and attached to the socket. | ||
25 | |||
26 | * Inbound Packet Processing | ||
27 | |||
28 | The CIPSO/IPv4 protocol engine validates every CIPSO IP option it finds at the | ||
29 | IP layer without any special handling required by the LSM. However, in order | ||
30 | to decode and translate the CIPSO label on the packet the LSM must use the | ||
31 | NetLabel security module API to extract the security attributes of the packet. | ||
32 | This is typically done at the socket layer using the 'socket_sock_rcv_skb()' | ||
33 | LSM hook. | ||
34 | |||
35 | * Label Translation | ||
36 | |||
37 | The CIPSO/IPv4 protocol engine contains a mechanism to translate CIPSO security | ||
38 | attributes such as sensitivity level and category to values which are | ||
39 | appropriate for the host. These mappings are defined as part of a CIPSO | ||
40 | Domain Of Interpretation (DOI) definition and are configured through the | ||
41 | NetLabel user space communication layer. Each DOI definition can have a | ||
42 | different security attribute mapping table. | ||
43 | |||
44 | * Label Translation Cache | ||
45 | |||
46 | The NetLabel system provides a framework for caching security attribute | ||
47 | mappings from the network labels to the corresponding LSM identifiers. The | ||
48 | CIPSO/IPv4 protocol engine supports this caching mechanism. | ||
diff --git a/Documentation/netlabel/draft-ietf-cipso-ipsecurity-01.txt b/Documentation/netlabel/draft-ietf-cipso-ipsecurity-01.txt new file mode 100644 index 000000000000..256c2c9d4f50 --- /dev/null +++ b/Documentation/netlabel/draft-ietf-cipso-ipsecurity-01.txt | |||
@@ -0,0 +1,791 @@ | |||
1 | IETF CIPSO Working Group | ||
2 | 16 July, 1992 | ||
3 | |||
4 | |||
5 | |||
6 | COMMERCIAL IP SECURITY OPTION (CIPSO 2.2) | ||
7 | |||
8 | |||
9 | |||
10 | 1. Status | ||
11 | |||
12 | This Internet Draft provides the high level specification for a Commercial | ||
13 | IP Security Option (CIPSO). This draft reflects the version as approved by | ||
14 | the CIPSO IETF Working Group. Distribution of this memo is unlimited. | ||
15 | |||
16 | This document is an Internet Draft. Internet Drafts are working documents | ||
17 | of the Internet Engineering Task Force (IETF), its Areas, and its Working | ||
18 | Groups. Note that other groups may also distribute working documents as | ||
19 | Internet Drafts. | ||
20 | |||
21 | Internet Drafts are draft documents valid for a maximum of six months. | ||
22 | Internet Drafts may be updated, replaced, or obsoleted by other documents | ||
23 | at any time. It is not appropriate to use Internet Drafts as reference | ||
24 | material or to cite them other than as a "working draft" or "work in | ||
25 | progress." | ||
26 | |||
27 | Please check the I-D abstract listing contained in each Internet Draft | ||
28 | directory to learn the current status of this or any other Internet Draft. | ||
29 | |||
30 | |||
31 | |||
32 | |||
33 | 2. Background | ||
34 | |||
35 | Currently the Internet Protocol includes two security options. One of | ||
36 | these options is the DoD Basic Security Option (BSO) (Type 130) which allows | ||
37 | IP datagrams to be labeled with security classifications. This option | ||
38 | provides sixteen security classifications and a variable number of handling | ||
39 | restrictions. To handle additional security information, such as security | ||
40 | categories or compartments, another security option (Type 133) exists and | ||
41 | is referred to as the DoD Extended Security Option (ESO). The values for | ||
42 | the fixed fields within these two options are administered by the Defense | ||
43 | Information Systems Agency (DISA). | ||
44 | |||
45 | Computer vendors are now building commercial operating systems with | ||
46 | mandatory access controls and multi-level security. These systems are | ||
47 | no longer built specifically for a particular group in the defense or | ||
48 | intelligence communities. They are generally available commercial systems | ||
49 | for use in a variety of government and civil sector environments. | ||
50 | |||
51 | The small number of ESO format codes can not support all the possible | ||
52 | applications of a commercial security option. The BSO and ESO were | ||
53 | designed to only support the United States DoD. CIPSO has been designed | ||
54 | to support multiple security policies. This Internet Draft provides the | ||
55 | format and procedures required to support a Mandatory Access Control | ||
56 | security policy. Support for additional security policies shall be | ||
57 | defined in future RFCs. | ||
58 | |||
59 | |||
60 | |||
61 | |||
62 | Internet Draft, Expires 15 Jan 93 [PAGE 1] | ||
63 | |||
64 | |||
65 | |||
66 | CIPSO INTERNET DRAFT 16 July, 1992 | ||
67 | |||
68 | |||
69 | |||
70 | |||
71 | 3. CIPSO Format | ||
72 | |||
73 | Option type: 134 (Class 0, Number 6, Copy on Fragmentation) | ||
74 | Option length: Variable | ||
75 | |||
76 | This option permits security related information to be passed between | ||
77 | systems within a single Domain of Interpretation (DOI). A DOI is a | ||
78 | collection of systems which agree on the meaning of particular values | ||
79 | in the security option. An authority that has been assigned a DOI | ||
80 | identifier will define a mapping between appropriate CIPSO field values | ||
81 | and their human readable equivalent. This authority will distribute that | ||
82 | mapping to hosts within the authority's domain. These mappings may be | ||
83 | sensitive, therefore a DOI authority is not required to make these | ||
84 | mappings available to anyone other than the systems that are included in | ||
85 | the DOI. | ||
86 | |||
87 | This option MUST be copied on fragmentation. This option appears at most | ||
88 | once in a datagram. All multi-octet fields in the option are defined to be | ||
89 | transmitted in network byte order. The format of this option is as follows: | ||
90 | |||
91 | +----------+----------+------//------+-----------//---------+ | ||
92 | | 10000110 | LLLLLLLL | DDDDDDDDDDDD | TTTTTTTTTTTTTTTTTTTT | | ||
93 | +----------+----------+------//------+-----------//---------+ | ||
94 | |||
95 | TYPE=134 OPTION DOMAIN OF TAGS | ||
96 | LENGTH INTERPRETATION | ||
97 | |||
98 | |||
99 | Figure 1. CIPSO Format | ||
100 | |||
101 | |||
102 | 3.1 Type | ||
103 | |||
104 | This field is 1 octet in length. Its value is 134. | ||
105 | |||
106 | |||
107 | 3.2 Length | ||
108 | |||
109 | This field is 1 octet in length. It is the total length of the option | ||
110 | including the type and length fields. With the current IP header length | ||
111 | restriction of 40 octets the value of this field MUST not exceed 40. | ||
112 | |||
113 | |||
114 | 3.3 Domain of Interpretation Identifier | ||
115 | |||
116 | This field is an unsigned 32 bit integer. The value 0 is reserved and MUST | ||
117 | not appear as the DOI identifier in any CIPSO option. Implementations | ||
118 | should assume that the DOI identifier field is not aligned on any particular | ||
119 | byte boundary. | ||
120 | |||
121 | To conserve space in the protocol, security levels and categories are | ||
122 | represented by numbers rather than their ASCII equivalent. This requires | ||
123 | a mapping table within CIPSO hosts to map these numbers to their | ||
124 | corresponding ASCII representations. Non-related groups of systems may | ||
125 | |||
126 | |||
127 | |||
128 | Internet Draft, Expires 15 Jan 93 [PAGE 2] | ||
129 | |||
130 | |||
131 | |||
132 | CIPSO INTERNET DRAFT 16 July, 1992 | ||
133 | |||
134 | |||
135 | |||
136 | have their own unique mappings. For example, one group of systems may | ||
137 | use the number 5 to represent Unclassified while another group may use the | ||
138 | number 1 to represent that same security level. The DOI identifier is used | ||
139 | to identify which mapping was used for the values within the option. | ||
140 | |||
141 | |||
142 | 3.4 Tag Types | ||
143 | |||
144 | A common format for passing security related information is necessary | ||
145 | for interoperability. CIPSO uses sets of "tags" to contain the security | ||
146 | information relevant to the data in the IP packet. Each tag begins with | ||
147 | a tag type identifier followed by the length of the tag and ends with the | ||
148 | actual security information to be passed. All multi-octet fields in a tag | ||
149 | are defined to be transmitted in network byte order. Like the DOI | ||
150 | identifier field in the CIPSO header, implementations should assume that | ||
151 | all tags, as well as fields within a tag, are not aligned on any particular | ||
152 | octet boundary. The tag types defined in this document contain alignment | ||
153 | bytes to assist alignment of some information, however alignment can not | ||
154 | be guaranteed if CIPSO is not the first IP option. | ||
155 | |||
156 | CIPSO tag types 0 through 127 are reserved for defining standard tag | ||
157 | formats. Their definitions will be published in RFCs. Tag types whose | ||
158 | identifiers are greater than 127 are defined by the DOI authority and may | ||
159 | only be meaningful in certain Domains of Interpretation. For these tag | ||
160 | types, implementations will require the DOI identifier as well as the tag | ||
161 | number to determine the security policy and the format associated with the | ||
162 | tag. Use of tag types above 127 are restricted to closed networks where | ||
163 | interoperability with other networks will not be an issue. Implementations | ||
164 | that support a tag type greater than 127 MUST support at least one DOI that | ||
165 | requires only tag types 1 to 127. | ||
166 | |||
167 | Tag type 0 is reserved. Tag types 1, 2, and 5 are defined in this | ||
168 | Internet Draft. Types 3 and 4 are reserved for work in progress. | ||
169 | The standard format for all current and future CIPSO tags is shown below: | ||
170 | |||
171 | +----------+----------+--------//--------+ | ||
172 | | TTTTTTTT | LLLLLLLL | IIIIIIIIIIIIIIII | | ||
173 | +----------+----------+--------//--------+ | ||
174 | TAG TAG TAG | ||
175 | TYPE LENGTH INFORMATION | ||
176 | |||
177 | Figure 2: Standard Tag Format | ||
178 | |||
179 | In the three tag types described in this document, the length and count | ||
180 | restrictions are based on the current IP limitation of 40 octets for all | ||
181 | IP options. If the IP header is later expanded, then the length and count | ||
182 | restrictions specified in this document may increase to use the full area | ||
183 | provided for IP options. | ||
184 | |||
185 | |||
186 | 3.4.1 Tag Type Classes | ||
187 | |||
188 | Tag classes consist of tag types that have common processing requirements | ||
189 | and support the same security policy. The three tags defined in this | ||
190 | Internet Draft belong to the Mandatory Access Control (MAC) Sensitivity | ||
191 | |||
192 | |||
193 | |||
194 | Internet Draft, Expires 15 Jan 93 [PAGE 3] | ||
195 | |||
196 | |||
197 | |||
198 | CIPSO INTERNET DRAFT 16 July, 1992 | ||
199 | |||
200 | |||
201 | |||
202 | class and support the MAC Sensitivity security policy. | ||
203 | |||
204 | |||
205 | 3.4.2 Tag Type 1 | ||
206 | |||
207 | This is referred to as the "bit-mapped" tag type. Tag type 1 is included | ||
208 | in the MAC Sensitivity tag type class. The format of this tag type is as | ||
209 | follows: | ||
210 | |||
211 | +----------+----------+----------+----------+--------//---------+ | ||
212 | | 00000001 | LLLLLLLL | 00000000 | LLLLLLLL | CCCCCCCCCCCCCCCCC | | ||
213 | +----------+----------+----------+----------+--------//---------+ | ||
214 | |||
215 | TAG TAG ALIGNMENT SENSITIVITY BIT MAP OF | ||
216 | TYPE LENGTH OCTET LEVEL CATEGORIES | ||
217 | |||
218 | Figure 3. Tag Type 1 Format | ||
219 | |||
220 | |||
221 | 3.4.2.1 Tag Type | ||
222 | |||
223 | This field is 1 octet in length and has a value of 1. | ||
224 | |||
225 | |||
226 | 3.4.2.2 Tag Length | ||
227 | |||
228 | This field is 1 octet in length. It is the total length of the tag type | ||
229 | including the type and length fields. With the current IP header length | ||
230 | restriction of 40 bytes the value within this field is between 4 and 34. | ||
231 | |||
232 | |||
233 | 3.4.2.3 Alignment Octet | ||
234 | |||
235 | This field is 1 octet in length and always has the value of 0. Its purpose | ||
236 | is to align the category bitmap field on an even octet boundary. This will | ||
237 | speed many implementations including router implementations. | ||
238 | |||
239 | |||
240 | 3.4.2.4 Sensitivity Level | ||
241 | |||
242 | This field is 1 octet in length. Its value is from 0 to 255. The values | ||
243 | are ordered with 0 being the minimum value and 255 representing the maximum | ||
244 | value. | ||
245 | |||
246 | |||
247 | 3.4.2.5 Bit Map of Categories | ||
248 | |||
249 | The length of this field is variable and ranges from 0 to 30 octets. This | ||
250 | provides representation of categories 0 to 239. The ordering of the bits | ||
251 | is left to right or MSB to LSB. For example category 0 is represented by | ||
252 | the most significant bit of the first byte and category 15 is represented | ||
253 | by the least significant bit of the second byte. Figure 4 graphically | ||
254 | shows this ordering. Bit N is binary 1 if category N is part of the label | ||
255 | for the datagram, and bit N is binary 0 if category N is not part of the | ||
256 | label. Except for the optimized tag 1 format described in the next section, | ||
257 | |||
258 | |||
259 | |||
260 | Internet Draft, Expires 15 Jan 93 [PAGE 4] | ||
261 | |||
262 | |||
263 | |||
264 | CIPSO INTERNET DRAFT 16 July, 1992 | ||
265 | |||
266 | |||
267 | |||
268 | minimal encoding SHOULD be used resulting in no trailing zero octets in the | ||
269 | category bitmap. | ||
270 | |||
271 | octet 0 octet 1 octet 2 octet 3 octet 4 octet 5 | ||
272 | XXXXXXXX XXXXXXXX XXXXXXXX XXXXXXXX XXXXXXXX XXXXXXXX . . . | ||
273 | bit 01234567 89111111 11112222 22222233 33333333 44444444 | ||
274 | number 012345 67890123 45678901 23456789 01234567 | ||
275 | |||
276 | Figure 4. Ordering of Bits in Tag 1 Bit Map | ||
277 | |||
278 | |||
279 | 3.4.2.6 Optimized Tag 1 Format | ||
280 | |||
281 | Routers work most efficiently when processing fixed length fields. To | ||
282 | support these routers there is an optimized form of tag type 1. The format | ||
283 | does not change. The only change is to the category bitmap which is set to | ||
284 | a constant length of 10 octets. Trailing octets required to fill out the 10 | ||
285 | octets are zero filled. Ten octets, allowing for 80 categories, was chosen | ||
286 | because it makes the total length of the CIPSO option 20 octets. If CIPSO | ||
287 | is the only option then the option will be full word aligned and additional | ||
288 | filler octets will not be required. | ||
289 | |||
290 | |||
291 | 3.4.3 Tag Type 2 | ||
292 | |||
293 | This is referred to as the "enumerated" tag type. It is used to describe | ||
294 | large but sparsely populated sets of categories. Tag type 2 is in the MAC | ||
295 | Sensitivity tag type class. The format of this tag type is as follows: | ||
296 | |||
297 | +----------+----------+----------+----------+-------------//-------------+ | ||
298 | | 00000010 | LLLLLLLL | 00000000 | LLLLLLLL | CCCCCCCCCCCCCCCCCCCCCCCCCC | | ||
299 | +----------+----------+----------+----------+-------------//-------------+ | ||
300 | |||
301 | TAG TAG ALIGNMENT SENSITIVITY ENUMERATED | ||
302 | TYPE LENGTH OCTET LEVEL CATEGORIES | ||
303 | |||
304 | Figure 5. Tag Type 2 Format | ||
305 | |||
306 | |||
307 | 3.4.3.1 Tag Type | ||
308 | |||
309 | This field is one octet in length and has a value of 2. | ||
310 | |||
311 | |||
312 | 3.4.3.2 Tag Length | ||
313 | |||
314 | This field is 1 octet in length. It is the total length of the tag type | ||
315 | including the type and length fields. With the current IP header length | ||
316 | restriction of 40 bytes the value within this field is between 4 and 34. | ||
317 | |||
318 | |||
319 | 3.4.3.3 Alignment Octet | ||
320 | |||
321 | This field is 1 octet in length and always has the value of 0. Its purpose | ||
322 | is to align the category field on an even octet boundary. This will | ||
323 | |||
324 | |||
325 | |||
326 | Internet Draft, Expires 15 Jan 93 [PAGE 5] | ||
327 | |||
328 | |||
329 | |||
330 | CIPSO INTERNET DRAFT 16 July, 1992 | ||
331 | |||
332 | |||
333 | |||
334 | speed many implementations including router implementations. | ||
335 | |||
336 | |||
337 | 3.4.3.4 Sensitivity Level | ||
338 | |||
339 | This field is 1 octet in length. Its value is from 0 to 255. The values | ||
340 | are ordered with 0 being the minimum value and 255 representing the | ||
341 | maximum value. | ||
342 | |||
343 | |||
344 | 3.4.3.5 Enumerated Categories | ||
345 | |||
346 | In this tag, categories are represented by their actual value rather than | ||
347 | by their position within a bit field. The length of each category is 2 | ||
348 | octets. Up to 15 categories may be represented by this tag. Valid values | ||
349 | for categories are 0 to 65534. Category 65535 is not a valid category | ||
350 | value. The categories MUST be listed in ascending order within the tag. | ||
351 | |||
352 | |||
353 | 3.4.4 Tag Type 5 | ||
354 | |||
355 | This is referred to as the "range" tag type. It is used to represent | ||
356 | labels where all categories in a range, or set of ranges, are included | ||
357 | in the sensitivity label. Tag type 5 is in the MAC Sensitivity tag type | ||
358 | class. The format of this tag type is as follows: | ||
359 | |||
360 | +----------+----------+----------+----------+------------//-------------+ | ||
361 | | 00000101 | LLLLLLLL | 00000000 | LLLLLLLL | Top/Bottom | Top/Bottom | | ||
362 | +----------+----------+----------+----------+------------//-------------+ | ||
363 | |||
364 | TAG TAG ALIGNMENT SENSITIVITY CATEGORY RANGES | ||
365 | TYPE LENGTH OCTET LEVEL | ||
366 | |||
367 | Figure 6. Tag Type 5 Format | ||
368 | |||
369 | |||
370 | 3.4.4.1 Tag Type | ||
371 | |||
372 | This field is one octet in length and has a value of 5. | ||
373 | |||
374 | |||
375 | 3.4.4.2 Tag Length | ||
376 | |||
377 | This field is 1 octet in length. It is the total length of the tag type | ||
378 | including the type and length fields. With the current IP header length | ||
379 | restriction of 40 bytes the value within this field is between 4 and 34. | ||
380 | |||
381 | |||
382 | 3.4.4.3 Alignment Octet | ||
383 | |||
384 | This field is 1 octet in length and always has the value of 0. Its purpose | ||
385 | is to align the category range field on an even octet boundary. This will | ||
386 | speed many implementations including router implementations. | ||
387 | |||
388 | |||
389 | |||
390 | |||
391 | |||
392 | Internet Draft, Expires 15 Jan 93 [PAGE 6] | ||
393 | |||
394 | |||
395 | |||
396 | CIPSO INTERNET DRAFT 16 July, 1992 | ||
397 | |||
398 | |||
399 | |||
400 | 3.4.4.4 Sensitivity Level | ||
401 | |||
402 | This field is 1 octet in length. Its value is from 0 to 255. The values | ||
403 | are ordered with 0 being the minimum value and 255 representing the maximum | ||
404 | value. | ||
405 | |||
406 | |||
407 | 3.4.4.5 Category Ranges | ||
408 | |||
409 | A category range is a 4 octet field comprised of the 2 octet index of the | ||
410 | highest numbered category followed by the 2 octet index of the lowest | ||
411 | numbered category. These range endpoints are inclusive within the range of | ||
412 | categories. All categories within a range are included in the sensitivity | ||
413 | label. This tag may contain a maximum of 7 category pairs. The bottom | ||
414 | category endpoint for the last pair in the tag MAY be omitted and SHOULD be | ||
415 | assumed to be 0. The ranges MUST be non-overlapping and be listed in | ||
416 | descending order. Valid values for categories are 0 to 65534. Category | ||
417 | 65535 is not a valid category value. | ||
418 | |||
419 | |||
420 | 3.4.5 Minimum Requirements | ||
421 | |||
422 | A CIPSO implementation MUST be capable of generating at least tag type 1 in | ||
423 | the non-optimized form. In addition, a CIPSO implementation MUST be able | ||
424 | to receive any valid tag type 1 even those using the optimized tag type 1 | ||
425 | format. | ||
426 | |||
427 | |||
428 | 4. Configuration Parameters | ||
429 | |||
430 | The configuration parameters defined below are required for all CIPSO hosts, | ||
431 | gateways, and routers that support multiple sensitivity labels. A CIPSO | ||
432 | host is defined to be the origination or destination system for an IP | ||
433 | datagram. A CIPSO gateway provides IP routing services between two or more | ||
434 | IP networks and may be required to perform label translations between | ||
435 | networks. A CIPSO gateway may be an enhanced CIPSO host or it may just | ||
436 | provide gateway services with no end system CIPSO capabilities. A CIPSO | ||
437 | router is a dedicated IP router that routes IP datagrams between two or more | ||
438 | IP networks. | ||
439 | |||
440 | An implementation of CIPSO on a host MUST have the capability to reject a | ||
441 | datagram for reasons that the information contained can not be adequately | ||
442 | protected by the receiving host or if acceptance may result in violation of | ||
443 | the host or network security policy. In addition, a CIPSO gateway or router | ||
444 | MUST be able to reject datagrams going to networks that can not provide | ||
445 | adequate protection or may violate the network's security policy. To | ||
446 | provide this capability the following minimal set of configuration | ||
447 | parameters are required for CIPSO implementations: | ||
448 | |||
449 | HOST_LABEL_MAX - This parameter contains the maximum sensitivity label that | ||
450 | a CIPSO host is authorized to handle. All datagrams that have a label | ||
451 | greater than this maximum MUST be rejected by the CIPSO host. This | ||
452 | parameter does not apply to CIPSO gateways or routers. This parameter need | ||
453 | not be defined explicitly as it can be implicitly derived from the | ||
454 | PORT_LABEL_MAX parameters for the associated interfaces. | ||
455 | |||
456 | |||
457 | |||
458 | Internet Draft, Expires 15 Jan 93 [PAGE 7] | ||
459 | |||
460 | |||
461 | |||
462 | CIPSO INTERNET DRAFT 16 July, 1992 | ||
463 | |||
464 | |||
465 | |||
466 | |||
467 | HOST_LABEL_MIN - This parameter contains the minimum sensitivity label that | ||
468 | a CIPSO host is authorized to handle. All datagrams that have a label less | ||
469 | than this minimum MUST be rejected by the CIPSO host. This parameter does | ||
470 | not apply to CIPSO gateways or routers. This parameter need not be defined | ||
471 | explicitly as it can be implicitly derived from the PORT_LABEL_MIN | ||
472 | parameters for the associated interfaces. | ||
473 | |||
474 | PORT_LABEL_MAX - This parameter contains the maximum sensitivity label for | ||
475 | all datagrams that may exit a particular network interface port. All | ||
476 | outgoing datagrams that have a label greater than this maximum MUST be | ||
477 | rejected by the CIPSO system. The label within this parameter MUST be | ||
478 | less than or equal to the label within the HOST_LABEL_MAX parameter. This | ||
479 | parameter does not apply to CIPSO hosts that support only one network port. | ||
480 | |||
481 | PORT_LABEL_MIN - This parameter contains the minimum sensitivity label for | ||
482 | all datagrams that may exit a particular network interface port. All | ||
483 | outgoing datagrams that have a label less than this minimum MUST be | ||
484 | rejected by the CIPSO system. The label within this parameter MUST be | ||
485 | greater than or equal to the label within the HOST_LABEL_MIN parameter. | ||
486 | This parameter does not apply to CIPSO hosts that support only one network | ||
487 | port. | ||
488 | |||
489 | PORT_DOI - This parameter is used to assign a DOI identifier value to a | ||
490 | particular network interface port. All CIPSO labels within datagrams | ||
491 | going out this port MUST use the specified DOI identifier. All CIPSO | ||
492 | hosts and gateways MUST support either this parameter, the NET_DOI | ||
493 | parameter, or the HOST_DOI parameter. | ||
494 | |||
495 | NET_DOI - This parameter is used to assign a DOI identifier value to a | ||
496 | particular IP network address. All CIPSO labels within datagrams destined | ||
497 | for the particular IP network MUST use the specified DOI identifier. All | ||
498 | CIPSO hosts and gateways MUST support either this parameter, the PORT_DOI | ||
499 | parameter, or the HOST_DOI parameter. | ||
500 | |||
501 | HOST_DOI - This parameter is used to assign a DOI identifier value to a | ||
502 | particular IP host address. All CIPSO labels within datagrams destined for | ||
503 | the particular IP host will use the specified DOI identifier. All CIPSO | ||
504 | hosts and gateways MUST support either this parameter, the PORT_DOI | ||
505 | parameter, or the NET_DOI parameter. | ||
506 | |||
507 | This list represents the minimal set of configuration parameters required | ||
508 | to be compliant. Implementors are encouraged to add to this list to | ||
509 | provide enhanced functionality and control. For example, many security | ||
510 | policies may require both incoming and outgoing datagrams be checked against | ||
511 | the port and host label ranges. | ||
512 | |||
513 | |||
514 | 4.1 Port Range Parameters | ||
515 | |||
516 | The labels represented by the PORT_LABEL_MAX and PORT_LABEL_MIN parameters | ||
517 | MAY be in CIPSO or local format. Some CIPSO systems, such as routers, may | ||
518 | want to have the range parameters expressed in CIPSO format so that incoming | ||
519 | labels do not have to be converted to a local format before being compared | ||
520 | against the range. If multiple DOIs are supported by one of these CIPSO | ||
521 | |||
522 | |||
523 | |||
524 | Internet Draft, Expires 15 Jan 93 [PAGE 8] | ||
525 | |||
526 | |||
527 | |||
528 | CIPSO INTERNET DRAFT 16 July, 1992 | ||
529 | |||
530 | |||
531 | |||
532 | systems then multiple port range parameters would be needed, one set for | ||
533 | each DOI supported on a particular port. | ||
534 | |||
535 | The port range will usually represent the total set of labels that may | ||
536 | exist on the logical network accessed through the corresponding network | ||
537 | interface. It may, however, represent a subset of these labels that are | ||
538 | allowed to enter the CIPSO system. | ||
539 | |||
540 | |||
541 | 4.2 Single Label CIPSO Hosts | ||
542 | |||
543 | CIPSO implementations that support only one label are not required to | ||
544 | support the parameters described above. These limited implementations are | ||
545 | only required to support a NET_LABEL parameter. This parameter contains | ||
546 | the CIPSO label that may be inserted in datagrams that exit the host. In | ||
547 | addition, the host MUST reject any incoming datagram that has a label which | ||
548 | is not equivalent to the NET_LABEL parameter. | ||
549 | |||
550 | |||
551 | 5. Handling Procedures | ||
552 | |||
553 | This section describes the processing requirements for incoming and | ||
554 | outgoing IP datagrams. Just providing the correct CIPSO label format | ||
555 | is not enough. Assumptions will be made by one system on how a | ||
556 | receiving system will handle the CIPSO label. Wrong assumptions may | ||
557 | lead to non-interoperability or even a security incident. The | ||
558 | requirements described below represent the minimal set needed for | ||
559 | interoperability and that provide users some level of confidence. | ||
560 | Many other requirements could be added to increase user confidence, | ||
561 | however at the risk of restricting creativity and limiting vendor | ||
562 | participation. | ||
563 | |||
564 | |||
565 | 5.1 Input Procedures | ||
566 | |||
567 | All datagrams received through a network port MUST have a security label | ||
568 | associated with them, either contained in the datagram or assigned to the | ||
569 | receiving port. Without this label the host, gateway, or router will not | ||
570 | have the information it needs to make security decisions. This security | ||
571 | label will be obtained from the CIPSO if the option is present in the | ||
572 | datagram. See section 4.1.2 for handling procedures for unlabeled | ||
573 | datagrams. This label will be compared against the PORT (if appropriate) | ||
574 | and HOST configuration parameters defined in section 3. | ||
575 | |||
576 | If any field within the CIPSO option, such as the DOI identifier, is not | ||
577 | recognized the IP datagram is discarded and an ICMP "parameter problem" | ||
578 | (type 12) is generated and returned. The ICMP code field is set to "bad | ||
579 | parameter" (code 0) and the pointer is set to the start of the CIPSO field | ||
580 | that is unrecognized. | ||
581 | |||
582 | If the contents of the CIPSO are valid but the security label is | ||
583 | outside of the configured host or port label range, the datagram is | ||
584 | discarded and an ICMP "destination unreachable" (type 3) is generated | ||
585 | and returned. The code field of the ICMP is set to "communication with | ||
586 | destination network administratively prohibited" (code 9) or to | ||
587 | |||
588 | |||
589 | |||
590 | Internet Draft, Expires 15 Jan 93 [PAGE 9] | ||
591 | |||
592 | |||
593 | |||
594 | CIPSO INTERNET DRAFT 16 July, 1992 | ||
595 | |||
596 | |||
597 | |||
598 | "communication with destination host administratively prohibited" | ||
599 | (code 10). The value of the code field used is dependent upon whether | ||
600 | the originator of the ICMP message is acting as a CIPSO host or a CIPSO | ||
601 | gateway. The recipient of the ICMP message MUST be able to handle either | ||
602 | value. The same procedure is performed if a CIPSO can not be added to an | ||
603 | IP packet because it is too large to fit in the IP options area. | ||
604 | |||
605 | If the error is triggered by receipt of an ICMP message, the message | ||
606 | is discarded and no response is permitted (consistent with general ICMP | ||
607 | processing rules). | ||
608 | |||
609 | |||
610 | 5.1.1 Unrecognized tag types | ||
611 | |||
612 | The default condition for any CIPSO implementation is that an | ||
613 | unrecognized tag type MUST be treated as a "parameter problem" and | ||
614 | handled as described in section 4.1. A CIPSO implementation MAY allow | ||
615 | the system administrator to identify tag types that may safely be | ||
616 | ignored. This capability is an allowable enhancement, not a | ||
617 | requirement. | ||
618 | |||
619 | |||
620 | 5.1.2 Unlabeled Packets | ||
621 | |||
622 | A network port may be configured to not require a CIPSO label for all | ||
623 | incoming datagrams. For this configuration a CIPSO label must be | ||
624 | assigned to that network port and associated with all unlabeled IP | ||
625 | datagrams. This capability might be used for single level networks or | ||
626 | networks that have CIPSO and non-CIPSO hosts and the non-CIPSO hosts | ||
627 | all operate at the same label. | ||
628 | |||
629 | If a CIPSO option is required and none is found, the datagram is | ||
630 | discarded and an ICMP "parameter problem" (type 12) is generated and | ||
631 | returned to the originator of the datagram. The code field of the ICMP | ||
632 | is set to "option missing" (code 1) and the ICMP pointer is set to 134 | ||
633 | (the value of the option type for the missing CIPSO option). | ||
634 | |||
635 | |||
636 | 5.2 Output Procedures | ||
637 | |||
638 | A CIPSO option MUST appear only once in a datagram. Only one tag type | ||
639 | from the MAC Sensitivity class MAY be included in a CIPSO option. Given | ||
640 | the current set of defined tag types, this means that CIPSO labels at | ||
641 | first will contain only one tag. | ||
642 | |||
643 | All datagrams leaving a CIPSO system MUST meet the following condition: | ||
644 | |||
645 | PORT_LABEL_MIN <= CIPSO label <= PORT_LABEL_MAX | ||
646 | |||
647 | If this condition is not satisfied the datagram MUST be discarded. | ||
648 | If the CIPSO system only supports one port, the HOST_LABEL_MIN and the | ||
649 | HOST_LABEL_MAX parameters MAY be substituted for the PORT parameters in | ||
650 | the above condition. | ||
651 | |||
652 | The DOI identifier to be used for all outgoing datagrams is configured by | ||
653 | |||
654 | |||
655 | |||
656 | Internet Draft, Expires 15 Jan 93 [PAGE 10] | ||
657 | |||
658 | |||
659 | |||
660 | CIPSO INTERNET DRAFT 16 July, 1992 | ||
661 | |||
662 | |||
663 | |||
664 | the administrator. If port level DOI identifier assignment is used, then | ||
665 | the PORT_DOI configuration parameter MUST contain the DOI identifier to | ||
666 | use. If network level DOI assignment is used, then the NET_DOI parameter | ||
667 | MUST contain the DOI identifier to use. And if host level DOI assignment | ||
668 | is employed, then the HOST_DOI parameter MUST contain the DOI identifier | ||
669 | to use. A CIPSO implementation need only support one level of DOI | ||
670 | assignment. | ||
671 | |||
672 | |||
673 | 5.3 DOI Processing Requirements | ||
674 | |||
675 | A CIPSO implementation MUST support at least one DOI and SHOULD support | ||
676 | multiple DOIs. System and network administrators are cautioned to | ||
677 | ensure that at least one DOI is common within an IP network to allow for | ||
678 | broadcasting of IP datagrams. | ||
679 | |||
680 | CIPSO gateways MUST be capable of translating a CIPSO option from one | ||
681 | DOI to another when forwarding datagrams between networks. For | ||
682 | efficiency purposes this capability is only a desired feature for CIPSO | ||
683 | routers. | ||
684 | |||
685 | |||
686 | 5.4 Label of ICMP Messages | ||
687 | |||
688 | The CIPSO label to be used on all outgoing ICMP messages MUST be equivalent | ||
689 | to the label of the datagram that caused the ICMP message. If the ICMP was | ||
690 | generated due to a problem associated with the original CIPSO label then the | ||
691 | following responses are allowed: | ||
692 | |||
693 | a. Use the CIPSO label of the original IP datagram | ||
694 | b. Drop the original datagram with no return message generated | ||
695 | |||
696 | In most cases these options will have the same effect. If you can not | ||
697 | interpret the label or if it is outside the label range of your host or | ||
698 | interface then an ICMP message with the same label will probably not be | ||
699 | able to exit the system. | ||
700 | |||
701 | |||
702 | 6. Assignment of DOI Identifier Numbers = | ||
703 | |||
704 | Requests for assignment of a DOI identifier number should be addressed to | ||
705 | the Internet Assigned Numbers Authority (IANA). | ||
706 | |||
707 | |||
708 | 7. Acknowledgements | ||
709 | |||
710 | Much of the material in this RFC is based on (and copied from) work | ||
711 | done by Gary Winiger of Sun Microsystems and published as Commercial | ||
712 | IP Security Option at the INTEROP 89, Commercial IPSO Workshop. | ||
713 | |||
714 | |||
715 | 8. Author's Address | ||
716 | |||
717 | To submit mail for distribution to members of the IETF CIPSO Working | ||
718 | Group, send mail to: cipso@wdl1.wdl.loral.com. | ||
719 | |||
720 | |||
721 | |||
722 | Internet Draft, Expires 15 Jan 93 [PAGE 11] | ||
723 | |||
724 | |||
725 | |||
726 | CIPSO INTERNET DRAFT 16 July, 1992 | ||
727 | |||
728 | |||
729 | |||
730 | |||
731 | To be added to or deleted from this distribution, send mail to: | ||
732 | cipso-request@wdl1.wdl.loral.com. | ||
733 | |||
734 | |||
735 | 9. References | ||
736 | |||
737 | RFC 1038, "Draft Revised IP Security Option", M. St. Johns, IETF, January | ||
738 | 1988. | ||
739 | |||
740 | RFC 1108, "U.S. Department of Defense Security Options | ||
741 | for the Internet Protocol", Stephen Kent, IAB, 1 March, 1991. | ||
742 | |||
743 | |||
744 | |||
745 | |||
746 | |||
747 | |||
748 | |||
749 | |||
750 | |||
751 | |||
752 | |||
753 | |||
754 | |||
755 | |||
756 | |||
757 | |||
758 | |||
759 | |||
760 | |||
761 | |||
762 | |||
763 | |||
764 | |||
765 | |||
766 | |||
767 | |||
768 | |||
769 | |||
770 | |||
771 | |||
772 | |||
773 | |||
774 | |||
775 | |||
776 | |||
777 | |||
778 | |||
779 | |||
780 | |||
781 | |||
782 | |||
783 | |||
784 | |||
785 | |||
786 | |||
787 | |||
788 | Internet Draft, Expires 15 Jan 93 [PAGE 12] | ||
789 | |||
790 | |||
791 | |||
diff --git a/Documentation/netlabel/introduction.txt b/Documentation/netlabel/introduction.txt new file mode 100644 index 000000000000..a4ffba1694c8 --- /dev/null +++ b/Documentation/netlabel/introduction.txt | |||
@@ -0,0 +1,46 @@ | |||
1 | NetLabel Introduction | ||
2 | ============================================================================== | ||
3 | Paul Moore, paul.moore@hp.com | ||
4 | |||
5 | August 2, 2006 | ||
6 | |||
7 | * Overview | ||
8 | |||
9 | NetLabel is a mechanism which can be used by kernel security modules to attach | ||
10 | security attributes to outgoing network packets generated from user space | ||
11 | applications and read security attributes from incoming network packets. It | ||
12 | is composed of three main components, the protocol engines, the communication | ||
13 | layer, and the kernel security module API. | ||
14 | |||
15 | * Protocol Engines | ||
16 | |||
17 | The protocol engines are responsible for both applying and retrieving the | ||
18 | network packet's security attributes. If any translation between the network | ||
19 | security attributes and those on the host are required then the protocol | ||
20 | engine will handle those tasks as well. Other kernel subsystems should | ||
21 | refrain from calling the protocol engines directly, instead they should use | ||
22 | the NetLabel kernel security module API described below. | ||
23 | |||
24 | Detailed information about each NetLabel protocol engine can be found in this | ||
25 | directory, consult '00-INDEX' for filenames. | ||
26 | |||
27 | * Communication Layer | ||
28 | |||
29 | The communication layer exists to allow NetLabel configuration and monitoring | ||
30 | from user space. The NetLabel communication layer uses a message based | ||
31 | protocol built on top of the Generic NETLINK transport mechanism. The exact | ||
32 | formatting of these NetLabel messages as well as the Generic NETLINK family | ||
33 | names can be found in the the 'net/netlabel/' directory as comments in the | ||
34 | header files as well as in 'include/net/netlabel.h'. | ||
35 | |||
36 | * Security Module API | ||
37 | |||
38 | The purpose of the NetLabel security module API is to provide a protocol | ||
39 | independent interface to the underlying NetLabel protocol engines. In addition | ||
40 | to protocol independence, the security module API is designed to be completely | ||
41 | LSM independent which should allow multiple LSMs to leverage the same code | ||
42 | base. | ||
43 | |||
44 | Detailed information about the NetLabel security module API can be found in the | ||
45 | 'include/net/netlabel.h' header file as well as the 'lsm_interface.txt' file | ||
46 | found in this directory. | ||
diff --git a/Documentation/netlabel/lsm_interface.txt b/Documentation/netlabel/lsm_interface.txt new file mode 100644 index 000000000000..98dd9f7430f2 --- /dev/null +++ b/Documentation/netlabel/lsm_interface.txt | |||
@@ -0,0 +1,47 @@ | |||
1 | NetLabel Linux Security Module Interface | ||
2 | ============================================================================== | ||
3 | Paul Moore, paul.moore@hp.com | ||
4 | |||
5 | May 17, 2006 | ||
6 | |||
7 | * Overview | ||
8 | |||
9 | NetLabel is a mechanism which can set and retrieve security attributes from | ||
10 | network packets. It is intended to be used by LSM developers who want to make | ||
11 | use of a common code base for several different packet labeling protocols. | ||
12 | The NetLabel security module API is defined in 'include/net/netlabel.h' but a | ||
13 | brief overview is given below. | ||
14 | |||
15 | * NetLabel Security Attributes | ||
16 | |||
17 | Since NetLabel supports multiple different packet labeling protocols and LSMs | ||
18 | it uses the concept of security attributes to refer to the packet's security | ||
19 | labels. The NetLabel security attributes are defined by the | ||
20 | 'netlbl_lsm_secattr' structure in the NetLabel header file. Internally the | ||
21 | NetLabel subsystem converts the security attributes to and from the correct | ||
22 | low-level packet label depending on the NetLabel build time and run time | ||
23 | configuration. It is up to the LSM developer to translate the NetLabel | ||
24 | security attributes into whatever security identifiers are in use for their | ||
25 | particular LSM. | ||
26 | |||
27 | * NetLabel LSM Protocol Operations | ||
28 | |||
29 | These are the functions which allow the LSM developer to manipulate the labels | ||
30 | on outgoing packets as well as read the labels on incoming packets. Functions | ||
31 | exist to operate both on sockets as well as the sk_buffs directly. These high | ||
32 | level functions are translated into low level protocol operations based on how | ||
33 | the administrator has configured the NetLabel subsystem. | ||
34 | |||
35 | * NetLabel Label Mapping Cache Operations | ||
36 | |||
37 | Depending on the exact configuration, translation between the network packet | ||
38 | label and the internal LSM security identifier can be time consuming. The | ||
39 | NetLabel label mapping cache is a caching mechanism which can be used to | ||
40 | sidestep much of this overhead once a mapping has been established. Once the | ||
41 | LSM has received a packet, used NetLabel to decode it's security attributes, | ||
42 | and translated the security attributes into a LSM internal identifier the LSM | ||
43 | can use the NetLabel caching functions to associate the LSM internal | ||
44 | identifier with the network packet's label. This means that in the future | ||
45 | when a incoming packet matches a cached value not only are the internal | ||
46 | NetLabel translation mechanisms bypassed but the LSM translation mechanisms are | ||
47 | bypassed as well which should result in a significant reduction in overhead. | ||
diff --git a/Documentation/networking/ip-sysctl.txt b/Documentation/networking/ip-sysctl.txt index 90ed78110fd4..935e298f674a 100644 --- a/Documentation/networking/ip-sysctl.txt +++ b/Documentation/networking/ip-sysctl.txt | |||
@@ -375,6 +375,41 @@ tcp_slow_start_after_idle - BOOLEAN | |||
375 | be timed out after an idle period. | 375 | be timed out after an idle period. |
376 | Default: 1 | 376 | Default: 1 |
377 | 377 | ||
378 | CIPSOv4 Variables: | ||
379 | |||
380 | cipso_cache_enable - BOOLEAN | ||
381 | If set, enable additions to and lookups from the CIPSO label mapping | ||
382 | cache. If unset, additions are ignored and lookups always result in a | ||
383 | miss. However, regardless of the setting the cache is still | ||
384 | invalidated when required when means you can safely toggle this on and | ||
385 | off and the cache will always be "safe". | ||
386 | Default: 1 | ||
387 | |||
388 | cipso_cache_bucket_size - INTEGER | ||
389 | The CIPSO label cache consists of a fixed size hash table with each | ||
390 | hash bucket containing a number of cache entries. This variable limits | ||
391 | the number of entries in each hash bucket; the larger the value the | ||
392 | more CIPSO label mappings that can be cached. When the number of | ||
393 | entries in a given hash bucket reaches this limit adding new entries | ||
394 | causes the oldest entry in the bucket to be removed to make room. | ||
395 | Default: 10 | ||
396 | |||
397 | cipso_rbm_optfmt - BOOLEAN | ||
398 | Enable the "Optimized Tag 1 Format" as defined in section 3.4.2.6 of | ||
399 | the CIPSO draft specification (see Documentation/netlabel for details). | ||
400 | This means that when set the CIPSO tag will be padded with empty | ||
401 | categories in order to make the packet data 32-bit aligned. | ||
402 | Default: 0 | ||
403 | |||
404 | cipso_rbm_structvalid - BOOLEAN | ||
405 | If set, do a very strict check of the CIPSO option when | ||
406 | ip_options_compile() is called. If unset, relax the checks done during | ||
407 | ip_options_compile(). Either way is "safe" as errors are caught else | ||
408 | where in the CIPSO processing code but setting this to 0 (False) should | ||
409 | result in less work (i.e. it should be faster) but could cause problems | ||
410 | with other implementations that require strict checking. | ||
411 | Default: 0 | ||
412 | |||
378 | IP Variables: | 413 | IP Variables: |
379 | 414 | ||
380 | ip_local_port_range - 2 INTEGERS | 415 | ip_local_port_range - 2 INTEGERS |
@@ -730,6 +765,9 @@ conf/all/forwarding - BOOLEAN | |||
730 | 765 | ||
731 | This referred to as global forwarding. | 766 | This referred to as global forwarding. |
732 | 767 | ||
768 | proxy_ndp - BOOLEAN | ||
769 | Do proxy ndp. | ||
770 | |||
733 | conf/interface/*: | 771 | conf/interface/*: |
734 | Change special settings per interface. | 772 | Change special settings per interface. |
735 | 773 | ||
diff --git a/Documentation/networking/secid.txt b/Documentation/networking/secid.txt new file mode 100644 index 000000000000..95ea06784333 --- /dev/null +++ b/Documentation/networking/secid.txt | |||
@@ -0,0 +1,14 @@ | |||
1 | flowi structure: | ||
2 | |||
3 | The secid member in the flow structure is used in LSMs (e.g. SELinux) to indicate | ||
4 | the label of the flow. This label of the flow is currently used in selecting | ||
5 | matching labeled xfrm(s). | ||
6 | |||
7 | If this is an outbound flow, the label is derived from the socket, if any, or | ||
8 | the incoming packet this flow is being generated as a response to (e.g. tcp | ||
9 | resets, timewait ack, etc.). It is also conceivable that the label could be | ||
10 | derived from other sources such as process context, device, etc., in special | ||
11 | cases, as may be appropriate. | ||
12 | |||
13 | If this is an inbound flow, the label is derived from the IPSec security | ||
14 | associations, if any, used by the packet. | ||
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). | |||
11 | Supported Cards/Chipsets | 11 | Supported 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 | ||
80 | People | 87 | People |
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 @@ | |||
1 | SAS Layer | ||
2 | --------- | ||
3 | |||
4 | The SAS Layer is a management infrastructure which manages | ||
5 | SAS LLDDs. It sits between SCSI Core and SAS LLDDs. The | ||
6 | layout is as follows: while SCSI Core is concerned with | ||
7 | SAM/SPC issues, and a SAS LLDD+sequencer is concerned with | ||
8 | phy/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 | |||
21 | A SAS LLDD is a PCI device driver. It is concerned with | ||
22 | phy/OOB management, and vendor specific tasks and generates | ||
23 | events to the SAS layer. | ||
24 | |||
25 | The SAS Layer does most SAS tasks as outlined in the SAS 1.1 | ||
26 | spec. | ||
27 | |||
28 | The sas_ha_struct describes the SAS LLDD to the SAS layer. | ||
29 | Most of it is used by the SAS Layer but a few fields need to | ||
30 | be initialized by the LLDDs. | ||
31 | |||
32 | After initializing your hardware, from the probe() function | ||
33 | you call sas_register_ha(). It will register your LLDD with | ||
34 | the SCSI subsystem, creating a SCSI host and it will | ||
35 | register your SAS driver with the sysfs SAS tree it creates. | ||
36 | It will then return. Then you enable your phys to actually | ||
37 | start OOB (at which point your driver will start calling the | ||
38 | notify_* event callbacks). | ||
39 | |||
40 | Structure descriptions: | ||
41 | |||
42 | struct sas_phy -------------------- | ||
43 | Normally this is statically embedded to your driver's | ||
44 | phy structure: | ||
45 | struct my_phy { | ||
46 | blah; | ||
47 | struct sas_phy sas_phy; | ||
48 | bleh; | ||
49 | }; | ||
50 | And then all the phys are an array of my_phy in your HA | ||
51 | struct (shown below). | ||
52 | |||
53 | Then as you go along and initialize your phys you also | ||
54 | initialize the sas_phy struct, along with your own | ||
55 | phy structure. | ||
56 | |||
57 | In general, the phys are managed by the LLDD and the ports | ||
58 | are managed by the SAS layer. So the phys are initialized | ||
59 | and updated by the LLDD and the ports are initialized and | ||
60 | updated by the SAS layer. | ||
61 | |||
62 | There is a scheme where the LLDD can RW certain fields, | ||
63 | and the SAS layer can only read such ones, and vice versa. | ||
64 | The idea is to avoid unnecessary locking. | ||
65 | |||
66 | enabled -- must be set (0/1) | ||
67 | id -- must be set [0,MAX_PHYS) | ||
68 | class, proto, type, role, oob_mode, linkrate -- must be set | ||
69 | oob_mode -- you set this when OOB has finished and then notify | ||
70 | the SAS Layer. | ||
71 | |||
72 | sas_addr -- this normally points to an array holding the sas | ||
73 | address of the phy, possibly somewhere in your my_phy | ||
74 | struct. | ||
75 | |||
76 | attached_sas_addr -- set this when you (LLDD) receive an | ||
77 | IDENTIFY frame or a FIS frame, _before_ notifying the SAS | ||
78 | layer. The idea is that sometimes the LLDD may want to fake | ||
79 | or provide a different SAS address on that phy/port and this | ||
80 | allows it to do this. At best you should copy the sas | ||
81 | address from the IDENTIFY frame or maybe generate a SAS | ||
82 | address for SATA directly attached devices. The Discover | ||
83 | process may later change this. | ||
84 | |||
85 | frame_rcvd -- this is where you copy the IDENTIFY/FIS frame | ||
86 | when you get it; you lock, copy, set frame_rcvd_size and | ||
87 | unlock the lock, and then call the event. It is a pointer | ||
88 | since there's no way to know your hw frame size _exactly_, | ||
89 | so you define the actual array in your phy struct and let | ||
90 | this pointer point to it. You copy the frame from your | ||
91 | DMAable memory to that area holding the lock. | ||
92 | |||
93 | sas_prim -- this is where primitives go when they're | ||
94 | received. See sas.h. Grab the lock, set the primitive, | ||
95 | release the lock, notify. | ||
96 | |||
97 | port -- this points to the sas_port if the phy belongs | ||
98 | to a port -- the LLDD only reads this. It points to the | ||
99 | sas_port this phy is part of. Set by the SAS Layer. | ||
100 | |||
101 | ha -- may be set; the SAS layer sets it anyway. | ||
102 | |||
103 | lldd_phy -- you should set this to point to your phy so you | ||
104 | can find your way around faster when the SAS layer calls one | ||
105 | of your callbacks and passes you a phy. If the sas_phy is | ||
106 | embedded you can also use container_of -- whatever you | ||
107 | prefer. | ||
108 | |||
109 | |||
110 | struct sas_port -------------------- | ||
111 | The LLDD doesn't set any fields of this struct -- it only | ||
112 | reads them. They should be self explanatory. | ||
113 | |||
114 | phy_mask is 32 bit, this should be enough for now, as I | ||
115 | haven't heard of a HA having more than 8 phys. | ||
116 | |||
117 | lldd_port -- I haven't found use for that -- maybe other | ||
118 | LLDD who wish to have internal port representation can make | ||
119 | use of this. | ||
120 | |||
121 | |||
122 | struct sas_ha_struct -------------------- | ||
123 | It normally is statically declared in your own LLDD | ||
124 | structure describing your adapter: | ||
125 | struct 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 | |||
135 | What needs to be initialized (sample function given below). | ||
136 | |||
137 | pcidev | ||
138 | sas_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. | ||
143 | sas_port | ||
144 | sas_phy -- an array of pointers to structures. (see | ||
145 | note above on sas_addr). | ||
146 | These must be set. See more notes below. | ||
147 | num_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 | |||
153 | The 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 | |||
160 | When sas_register_ha() returns, those are set and can be | ||
161 | called by the LLDD to notify the SAS layer of such events | ||
162 | the SAS layer. | ||
163 | |||
164 | The 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 | |||
170 | If the LLDD wants notification when a port has been formed | ||
171 | or deformed it sets those to a function satisfying the type. | ||
172 | |||
173 | A SAS LLDD should also implement at least one of the Task | ||
174 | Management 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 | |||
185 | For more information please read SAM from T10.org. | ||
186 | |||
187 | Port 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 | |||
193 | A SAS LLDD should implement at least one of those. | ||
194 | |||
195 | Phy management: | ||
196 | |||
197 | /* Phy management */ | ||
198 | int (*lldd_control_phy)(struct sas_phy *, enum phy_func); | ||
199 | |||
200 | lldd_ha -- set this to point to your HA struct. You can also | ||
201 | use container_of if you embedded it as shown above. | ||
202 | |||
203 | A sample initialization and registration function | ||
204 | can look like this (called last thing from probe()) | ||
205 | *but* before you enable the phys to do OOB: | ||
206 | |||
207 | static 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 | ||
251 | lines of a task collector. What it tells the SAS Layer is | ||
252 | whether the SAS layer should run in Direct Mode (default: | ||
253 | value 0 or 1) or Task Collector Mode (value greater than 1). | ||
254 | |||
255 | In Direct Mode, the SAS Layer calls Execute Task as soon as | ||
256 | it has a command to send to the SDS, _and_ this is a single | ||
257 | command, i.e. not linked. | ||
258 | |||
259 | Some hardware (e.g. aic94xx) has the capability to DMA more | ||
260 | than one task at a time (interrupt) from host memory. Task | ||
261 | Collector Mode is an optional feature for HAs which support | ||
262 | this in their hardware. (Again, it is completely optional | ||
263 | even if your hardware supports it.) | ||
264 | |||
265 | In Task Collector Mode, the SAS Layer would do _natural_ | ||
266 | coalescing of tasks and at the appropriate moment it would | ||
267 | call your driver to DMA more than one task in a single HA | ||
268 | interrupt. DMBS may want to use this by insmod/modprobe | ||
269 | setting the lldd_max_execute_num to something greater than | ||
270 | 1. | ||
271 | |||
272 | (2) SAS 1.1 does not define I_T Nexus Reset TMF. | ||
273 | |||
274 | Events | ||
275 | ------ | ||
276 | |||
277 | Events are _the only way_ a SAS LLDD notifies the SAS layer | ||
278 | of anything. There is no other method or way a LLDD to tell | ||
279 | the SAS layer of anything happening internally or in the SAS | ||
280 | domain. | ||
281 | |||
282 | Phy events: | ||
283 | PHYE_LOSS_OF_SIGNAL, (C) | ||
284 | PHYE_OOB_DONE, | ||
285 | PHYE_OOB_ERROR, (C) | ||
286 | PHYE_SPINUP_HOLD. | ||
287 | |||
288 | Port 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 | |||
295 | Host Adapter event: | ||
296 | HAE_RESET | ||
297 | |||
298 | A 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 | |||
305 | Meaning: | ||
306 | |||
307 | HAE_RESET -- when your HA got internal error and was reset. | ||
308 | |||
309 | PORTE_BYTES_DMAED -- on receiving an IDENTIFY/FIS frame | ||
310 | PORTE_BROADCAST_RCVD -- on receiving a primitive | ||
311 | PORTE_LINK_RESET_ERR -- timer expired, loss of signal, loss | ||
312 | of DWS, etc. (*) | ||
313 | PORTE_TIMER_EVENT -- DWS reset timeout timer expired (*) | ||
314 | PORTE_HARD_RESET -- Hard Reset primitive received. | ||
315 | |||
316 | PHYE_LOSS_OF_SIGNAL -- the device is gone (*) | ||
317 | PHYE_OOB_DONE -- OOB went fine and oob_mode is valid | ||
318 | PHYE_OOB_ERROR -- Error while doing OOB, the device probably | ||
319 | got disconnected. (*) | ||
320 | PHYE_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 | |||
326 | The Execute Command SCSI RPC: | ||
327 | |||
328 | int (*lldd_execute_task)(struct sas_task *, int num, | ||
329 | unsigned long gfp_flags); | ||
330 | |||
331 | Used to queue a task to the SAS LLDD. @task is the tasks to | ||
332 | be executed. @num should be the number of tasks being | ||
333 | queued at this function call (they are linked listed via | ||
334 | task::list), @gfp_mask should be the gfp_mask defining the | ||
335 | context of the caller. | ||
336 | |||
337 | This function should implement the Execute Command SCSI RPC, | ||
338 | or if you're sending a SCSI Task as linked commands, you | ||
339 | should also use this function. | ||
340 | |||
341 | That is, when lldd_execute_task() is called, the command(s) | ||
342 | go out on the transport *immediately*. There is *no* | ||
343 | queuing of any sort and at any level in a SAS LLDD. | ||
344 | |||
345 | The use of task::list is two-fold, one for linked commands, | ||
346 | the other discussed below. | ||
347 | |||
348 | It is possible to queue up more than one task at a time, by | ||
349 | initializing the list element of struct sas_task, and | ||
350 | passing the number of tasks enlisted in this manner in num. | ||
351 | |||
352 | Returns: -SAS_QUEUE_FULL, -ENOMEM, nothing was queued; | ||
353 | 0, the task(s) were queued. | ||
354 | |||
355 | If you want to pass num > 1, then either | ||
356 | A) you're the only caller of this function and keep track | ||
357 | of what you've queued to the LLDD, or | ||
358 | B) you know what you're doing and have a strategy of | ||
359 | retrying. | ||
360 | |||
361 | As opposed to queuing one task at a time (function call), | ||
362 | batch queuing of tasks, by having num > 1, greatly | ||
363 | simplifies LLDD code, sequencer code, and _hardware design_, | ||
364 | and has some performance advantages in certain situations | ||
365 | (DBMS). | ||
366 | |||
367 | The LLDD advertises if it can take more than one command at | ||
368 | a time at lldd_execute_task(), by setting the | ||
369 | lldd_max_execute_num parameter (controlled by "collector" | ||
370 | module parameter in aic94xx SAS LLDD). | ||
371 | |||
372 | You should leave this to the default 1, unless you know what | ||
373 | you're doing. | ||
374 | |||
375 | This is a function of the LLDD, to which the SAS layer can | ||
376 | cater to. | ||
377 | |||
378 | int lldd_queue_size | ||
379 | The host adapter's queue size. This is the maximum | ||
380 | number of commands the lldd can have pending to domain | ||
381 | devices on behalf of all upper layers submitting through | ||
382 | lldd_execute_task(). | ||
383 | |||
384 | You really want to set this to something (much) larger than | ||
385 | 1. | ||
386 | |||
387 | This _really_ has absolutely nothing to do with queuing. | ||
388 | There is no queuing in SAS LLDDs. | ||
389 | |||
390 | struct 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 | |||
401 | When an external entity, entity other than the LLDD or the | ||
402 | SAS Layer, wants to work with a struct domain_device, it | ||
403 | _must_ call kobject_get() when getting a handle on the | ||
404 | device and kobject_put() when it is done with the device. | ||
405 | |||
406 | This 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 | |||
416 | DISCOVERY | ||
417 | --------- | ||
418 | |||
419 | The 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 | |||
425 | This is a link to the tree(1) program, very useful in | ||
426 | viewing the SAS domain: | ||
427 | ftp://mama.indstate.edu/linux/tree/ | ||
428 | I expect user space applications to actually create a | ||
429 | graphical interface of this. | ||
430 | |||
431 | That is, the sysfs domain tree doesn't show or keep state if | ||
432 | you e.g., change the meaning of the READY LED MEANING | ||
433 | setting, but it does show you the current connection status | ||
434 | of the domain device. | ||
435 | |||
436 | Keeping internal device state changes is responsibility of | ||
437 | upper layers (Command set drivers) and user space. | ||
438 | |||
439 | When a device or devices are unplugged from the domain, this | ||
440 | is reflected in the sysfs tree immediately, and the device(s) | ||
441 | removed from the system. | ||
442 | |||
443 | The structure domain_device describes any device in the SAS | ||
444 | domain. It is completely managed by the SAS layer. A task | ||
445 | points to a domain device, this is how the SAS LLDD knows | ||
446 | where to send the task(s) to. A SAS LLDD only reads the | ||
447 | contents of the domain_device structure, but it never creates | ||
448 | or destroys one. | ||
449 | |||
450 | Expander management from User Space | ||
451 | ----------------------------------- | ||
452 | |||
453 | In each expander directory in sysfs, there is a file called | ||
454 | "smp_portal". It is a binary sysfs attribute file, which | ||
455 | implements an SMP portal (Note: this is *NOT* an SMP port), | ||
456 | to which user space applications can send SMP requests and | ||
457 | receive SMP responses. | ||
458 | |||
459 | Functionality is deceptively simple: | ||
460 | |||
461 | 1. 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. | ||
463 | open(2) | ||
464 | 2. Open the expander's SMP portal sysfs file in RW mode. | ||
465 | write(2) | ||
466 | 3. Write the frame you built in 1. | ||
467 | read(2) | ||
468 | 4. 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. | ||
471 | close(2) | ||
472 | All this process is shown in detail in the function do_smp_func() | ||
473 | and its callers, in the file "expander_conf.c". | ||
474 | |||
475 | The kernel functionality is implemented in the file | ||
476 | "sas_expander.c". | ||
477 | |||
478 | The program "expander_conf.c" implements this. It takes one | ||
479 | argument, the sysfs file name of the SMP portal to the | ||
480 | expander, and gives expander information, including routing | ||
481 | tables. | ||
482 | |||
483 | The SMP portal gives you complete control of the expander, | ||
484 | so please be careful. | ||
diff --git a/Documentation/sound/alsa/ALSA-Configuration.txt b/Documentation/sound/alsa/ALSA-Configuration.txt index f61af23dd85d..e6b57dd46a4f 100644 --- a/Documentation/sound/alsa/ALSA-Configuration.txt +++ b/Documentation/sound/alsa/ALSA-Configuration.txt | |||
@@ -758,6 +758,7 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. | |||
758 | position_fix - Fix DMA pointer (0 = auto, 1 = none, 2 = POSBUF, 3 = FIFO size) | 758 | position_fix - Fix DMA pointer (0 = auto, 1 = none, 2 = POSBUF, 3 = FIFO size) |
759 | single_cmd - Use single immediate commands to communicate with | 759 | single_cmd - Use single immediate commands to communicate with |
760 | codecs (for debugging only) | 760 | codecs (for debugging only) |
761 | disable_msi - Disable Message Signaled Interrupt (MSI) | ||
761 | 762 | ||
762 | This module supports one card and autoprobe. | 763 | This module supports one card and autoprobe. |
763 | 764 | ||
@@ -778,11 +779,16 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. | |||
778 | 6stack-digout 6-jack with a SPDIF out | 779 | 6stack-digout 6-jack with a SPDIF out |
779 | w810 3-jack | 780 | w810 3-jack |
780 | z71v 3-jack (HP shared SPDIF) | 781 | z71v 3-jack (HP shared SPDIF) |
781 | asus 3-jack | 782 | asus 3-jack (ASUS Mobo) |
783 | asus-w1v ASUS W1V | ||
784 | asus-dig ASUS with SPDIF out | ||
785 | asus-dig2 ASUS with SPDIF out (using GPIO2) | ||
782 | uniwill 3-jack | 786 | uniwill 3-jack |
783 | F1734 2-jack | 787 | F1734 2-jack |
784 | lg LG laptop (m1 express dual) | 788 | lg LG laptop (m1 express dual) |
785 | lg-lw LG LW20 laptop | 789 | lg-lw LG LW20/LW25 laptop |
790 | tcl TCL S700 | ||
791 | clevo Clevo laptops (m520G, m665n) | ||
786 | test for testing/debugging purpose, almost all controls can be | 792 | test for testing/debugging purpose, almost all controls can be |
787 | adjusted. Appearing only when compiled with | 793 | adjusted. Appearing only when compiled with |
788 | $CONFIG_SND_DEBUG=y | 794 | $CONFIG_SND_DEBUG=y |
@@ -790,6 +796,7 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. | |||
790 | 796 | ||
791 | ALC260 | 797 | ALC260 |
792 | hp HP machines | 798 | hp HP machines |
799 | hp-3013 HP machines (3013-variant) | ||
793 | fujitsu Fujitsu S7020 | 800 | fujitsu Fujitsu S7020 |
794 | acer Acer TravelMate | 801 | acer Acer TravelMate |
795 | basic fixed pin assignment (old default model) | 802 | basic fixed pin assignment (old default model) |
@@ -797,24 +804,32 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. | |||
797 | 804 | ||
798 | ALC262 | 805 | ALC262 |
799 | fujitsu Fujitsu Laptop | 806 | fujitsu Fujitsu Laptop |
807 | hp-bpc HP xw4400/6400/8400/9400 laptops | ||
808 | benq Benq ED8 | ||
800 | basic fixed pin assignment w/o SPDIF | 809 | basic fixed pin assignment w/o SPDIF |
801 | auto auto-config reading BIOS (default) | 810 | auto auto-config reading BIOS (default) |
802 | 811 | ||
803 | ALC882/885 | 812 | ALC882/885 |
804 | 3stack-dig 3-jack with SPDIF I/O | 813 | 3stack-dig 3-jack with SPDIF I/O |
805 | 6stck-dig 6-jack digital with SPDIF I/O | 814 | 6stck-dig 6-jack digital with SPDIF I/O |
815 | arima Arima W820Di1 | ||
806 | auto auto-config reading BIOS (default) | 816 | auto auto-config reading BIOS (default) |
807 | 817 | ||
808 | ALC883/888 | 818 | ALC883/888 |
809 | 3stack-dig 3-jack with SPDIF I/O | 819 | 3stack-dig 3-jack with SPDIF I/O |
810 | 6stack-dig 6-jack digital with SPDIF I/O | 820 | 6stack-dig 6-jack digital with SPDIF I/O |
811 | 6stack-dig-demo 6-stack digital for Intel demo board | 821 | 3stack-6ch 3-jack 6-channel |
822 | 3stack-6ch-dig 3-jack 6-channel with SPDIF I/O | ||
823 | 6stack-dig-demo 6-jack digital for Intel demo board | ||
824 | acer Acer laptops (Travelmate 3012WTMi, Aspire 5600, etc) | ||
812 | auto auto-config reading BIOS (default) | 825 | auto auto-config reading BIOS (default) |
813 | 826 | ||
814 | ALC861/660 | 827 | ALC861/660 |
815 | 3stack 3-jack | 828 | 3stack 3-jack |
816 | 3stack-dig 3-jack with SPDIF I/O | 829 | 3stack-dig 3-jack with SPDIF I/O |
817 | 6stack-dig 6-jack with SPDIF I/O | 830 | 6stack-dig 6-jack with SPDIF I/O |
831 | 3stack-660 3-jack (for ALC660) | ||
832 | uniwill-m31 Uniwill M31 laptop | ||
818 | auto auto-config reading BIOS (default) | 833 | auto auto-config reading BIOS (default) |
819 | 834 | ||
820 | CMI9880 | 835 | CMI9880 |
@@ -843,10 +858,21 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. | |||
843 | 3stack-dig ditto with SPDIF | 858 | 3stack-dig ditto with SPDIF |
844 | laptop 3-jack with hp-jack automute | 859 | laptop 3-jack with hp-jack automute |
845 | laptop-dig ditto with SPDIF | 860 | laptop-dig ditto with SPDIF |
846 | auto auto-confgi reading BIOS (default) | 861 | auto auto-config reading BIOS (default) |
862 | |||
863 | STAC9200/9205/9220/9221/9254 | ||
864 | ref Reference board | ||
865 | 3stack D945 3stack | ||
866 | 5stack D945 5stack + SPDIF | ||
847 | 867 | ||
848 | STAC7661(?) | 868 | STAC9227/9228/9229/927x |
869 | ref Reference board | ||
870 | 3stack D965 3stack | ||
871 | 5stack D965 5stack + SPDIF | ||
872 | |||
873 | STAC9872 | ||
849 | vaio Setup for VAIO FE550G/SZ110 | 874 | vaio Setup for VAIO FE550G/SZ110 |
875 | vaio-ar Setup for VAIO AR | ||
850 | 876 | ||
851 | If the default configuration doesn't work and one of the above | 877 | If the default configuration doesn't work and one of the above |
852 | matches with your device, report it together with the PCI | 878 | matches with your device, report it together with the PCI |
@@ -1213,6 +1239,14 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. | |||
1213 | 1239 | ||
1214 | Module supports only 1 card. This module has no enable option. | 1240 | Module supports only 1 card. This module has no enable option. |
1215 | 1241 | ||
1242 | Module snd-mts64 | ||
1243 | ---------------- | ||
1244 | |||
1245 | Module for Ego Systems (ESI) Miditerminal 4140 | ||
1246 | |||
1247 | This module supports multiple devices. | ||
1248 | Requires parport (CONFIG_PARPORT). | ||
1249 | |||
1216 | Module snd-nm256 | 1250 | Module snd-nm256 |
1217 | ---------------- | 1251 | ---------------- |
1218 | 1252 | ||
diff --git a/Documentation/sound/alsa/DocBook/writing-an-alsa-driver.tmpl b/Documentation/sound/alsa/DocBook/writing-an-alsa-driver.tmpl index b8dc51ca776c..4807ef79a94d 100644 --- a/Documentation/sound/alsa/DocBook/writing-an-alsa-driver.tmpl +++ b/Documentation/sound/alsa/DocBook/writing-an-alsa-driver.tmpl | |||
@@ -1054,9 +1054,8 @@ | |||
1054 | 1054 | ||
1055 | <para> | 1055 | <para> |
1056 | For a device which allows hotplugging, you can use | 1056 | For a device which allows hotplugging, you can use |
1057 | <function>snd_card_free_in_thread</function>. This one will | 1057 | <function>snd_card_free_when_closed</function>. This one will |
1058 | postpone the destruction and wait in a kernel-thread until all | 1058 | postpone the destruction until all devices are closed. |
1059 | devices are closed. | ||
1060 | </para> | 1059 | </para> |
1061 | 1060 | ||
1062 | </section> | 1061 | </section> |