1 /*
2  * Intel Wireless WiMax Connection 2400m
3  * Host-Device protocol interface definitions
4  *
5  *
6  * Copyright (C) 2007-2008 Intel Corporation. All rights reserved.
7  *
8  * Redistribution and use in source and binary forms, with or without
9  * modification, are permitted provided that the following conditions
10  * are met:
11  *
12  *   * Redistributions of source code must retain the above copyright
13  *     notice, this list of conditions and the following disclaimer.
14  *   * Redistributions in binary form must reproduce the above copyright
15  *     notice, this list of conditions and the following disclaimer in
16  *     the documentation and/or other materials provided with the
17  *     distribution.
18  *   * Neither the name of Intel Corporation nor the names of its
19  *     contributors may be used to endorse or promote products derived
20  *     from this software without specific prior written permission.
21  *
22  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
23  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
24  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
25  * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
26  * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
27  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
28  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
29  * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
30  * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
31  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
32  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
33  *
34  *
35  * Intel Corporation <linux-wimax@intel.com>
36  * Inaky Perez-Gonzalez <inaky.perez-gonzalez@intel.com>
37  *  - Initial implementation
38  *
39  *
40  * This header defines the data structures and constants used to
41  * communicate with the device.
42  *
43  * BOOTMODE/BOOTROM/FIRMWARE UPLOAD PROTOCOL
44  *
45  * The firmware upload protocol is quite simple and only requires a
46  * handful of commands. See drivers/net/wimax/i2400m/fw.c for more
47  * details.
48  *
49  * The BCF data structure is for the firmware file header.
50  *
51  *
52  * THE DATA / CONTROL PROTOCOL
53  *
54  * This is the normal protocol spoken with the device once the
55  * firmware is uploaded. It transports data payloads and control
56  * messages back and forth.
57  *
58  * It consists 'messages' that pack one or more payloads each. The
59  * format is described in detail in drivers/net/wimax/i2400m/rx.c and
60  * tx.c.
61  *
62  *
63  * THE L3L4 PROTOCOL
64  *
65  * The term L3L4 refers to Layer 3 (the device), Layer 4 (the
66  * driver/host software).
67  *
68  * This is the control protocol used by the host to control the i2400m
69  * device (scan, connect, disconnect...). This is sent to / received
70  * as control frames. These frames consist of a header and zero or
71  * more TLVs with information. We call each control frame a "message".
72  *
73  * Each message is composed of:
74  *
75  * HEADER
76  * [TLV0 + PAYLOAD0]
77  * [TLV1 + PAYLOAD1]
78  * [...]
79  * [TLVN + PAYLOADN]
80  *
81  * The HEADER is defined by 'struct i2400m_l3l4_hdr'. The payloads are
82  * defined by a TLV structure (Type Length Value) which is a 'header'
83  * (struct i2400m_tlv_hdr) and then the payload.
84  *
85  * All integers are represented as Little Endian.
86  *
87  * - REQUESTS AND EVENTS
88  *
89  * The requests can be clasified as follows:
90  *
91  *   COMMAND:  implies a request from the host to the device requesting
92  *             an action being performed. The device will reply with a
93  *             message (with the same type as the command), status and
94  *             no (TLV) payload. Execution of a command might cause
95  *             events (of different type) to be sent later on as
96  *             device's state changes.
97  *
98  *   GET/SET:  similar to COMMAND, but will not cause other
99  *             EVENTs. The reply, in the case of GET, will contain
100  *             TLVs with the requested information.
101  *
102  *   EVENT:    asynchronous messages sent from the device, maybe as a
103  *             consequence of previous COMMANDs but disassociated from
104  *             them.
105  *
106  * Only one request might be pending at the same time (ie: don't
107  * parallelize nor post another GET request before the previous
108  * COMMAND has been acknowledged with it's corresponding reply by the
109  * device).
110  *
111  * The different requests and their formats are described below:
112  *
113  *  I2400M_MT_*   Message types
114  *  I2400M_MS_*   Message status (for replies, events)
115  *  i2400m_tlv_*  TLVs
116  *
117  * data types are named 'struct i2400m_msg_OPNAME', OPNAME matching the
118  * operation.
119  */
120 
121 #ifndef __LINUX__WIMAX__I2400M_H__
122 #define __LINUX__WIMAX__I2400M_H__
123 
124 #include <linux/types.h>
125 
126 
127 /*
128  * Host Device Interface (HDI) common to all busses
129  */
130 
131 /* Boot-mode (firmware upload mode) commands */
132 
133 /* Header for the firmware file */
134 struct i2400m_bcf_hdr {
135 	__le32 module_type;
136 	__le32 header_len;
137 	__le32 header_version;
138 	__le32 module_id;
139 	__le32 module_vendor;
140 	__le32 date;		/* BCD YYYMMDD */
141 	__le32 size;            /* in dwords */
142 	__le32 key_size;	/* in dwords */
143 	__le32 modulus_size;	/* in dwords */
144 	__le32 exponent_size;	/* in dwords */
145 	__u8 reserved[88];
146 } __attribute__ ((packed));
147 
148 /* Boot mode opcodes */
149 enum i2400m_brh_opcode {
150 	I2400M_BRH_READ = 1,
151 	I2400M_BRH_WRITE = 2,
152 	I2400M_BRH_JUMP = 3,
153 	I2400M_BRH_SIGNED_JUMP = 8,
154 	I2400M_BRH_HASH_PAYLOAD_ONLY = 9,
155 };
156 
157 /* Boot mode command masks and stuff */
158 enum i2400m_brh {
159 	I2400M_BRH_SIGNATURE = 0xcbbc0000,
160 	I2400M_BRH_SIGNATURE_MASK = 0xffff0000,
161 	I2400M_BRH_SIGNATURE_SHIFT = 16,
162 	I2400M_BRH_OPCODE_MASK = 0x0000000f,
163 	I2400M_BRH_RESPONSE_MASK = 0x000000f0,
164 	I2400M_BRH_RESPONSE_SHIFT = 4,
165 	I2400M_BRH_DIRECT_ACCESS = 0x00000400,
166 	I2400M_BRH_RESPONSE_REQUIRED = 0x00000200,
167 	I2400M_BRH_USE_CHECKSUM = 0x00000100,
168 };
169 
170 
171 /**
172  * i2400m_bootrom_header - Header for a boot-mode command
173  *
174  * @cmd: the above command descriptor
175  * @target_addr: where on the device memory should the action be performed.
176  * @data_size: for read/write, amount of data to be read/written
177  * @block_checksum: checksum value (if applicable)
178  * @payload: the beginning of data attached to this header
179  */
180 struct i2400m_bootrom_header {
181 	__le32 command;		/* Compose with enum i2400_brh */
182 	__le32 target_addr;
183 	__le32 data_size;
184 	__le32 block_checksum;
185 	char payload[0];
186 } __attribute__ ((packed));
187 
188 
189 /*
190  * Data / control protocol
191  */
192 
193 /* Packet types for the host-device interface */
194 enum i2400m_pt {
195 	I2400M_PT_DATA = 0,
196 	I2400M_PT_CTRL,
197 	I2400M_PT_TRACE,	/* For device debug */
198 	I2400M_PT_RESET_WARM,	/* device reset */
199 	I2400M_PT_RESET_COLD,	/* USB[transport] reset, like reconnect */
200 	I2400M_PT_EDATA,	/* Extended RX data */
201 	I2400M_PT_ILLEGAL
202 };
203 
204 
205 /*
206  * Payload for a data packet
207  *
208  * This is prefixed to each and every outgoing DATA type.
209  */
210 struct i2400m_pl_data_hdr {
211 	__le32 reserved;
212 } __attribute__((packed));
213 
214 
215 /*
216  * Payload for an extended data packet
217  *
218  * New in fw v1.4
219  *
220  * @reorder: if this payload has to be reorder or not (and how)
221  * @cs: the type of data in the packet, as defined per (802.16e
222  *     T11.13.19.1). Currently only 2 (IPv4 packet) supported.
223  *
224  * This is prefixed to each and every INCOMING DATA packet.
225  */
226 struct i2400m_pl_edata_hdr {
227 	__le32 reorder;		/* bits defined in i2400m_ro */
228 	__u8 cs;
229 	__u8 reserved[11];
230 } __attribute__((packed));
231 
232 enum i2400m_cs {
233 	I2400M_CS_IPV4_0 = 0,
234 	I2400M_CS_IPV4 = 2,
235 };
236 
237 enum i2400m_ro {
238 	I2400M_RO_NEEDED     = 0x01,
239 	I2400M_RO_TYPE       = 0x03,
240 	I2400M_RO_TYPE_SHIFT = 1,
241 	I2400M_RO_CIN        = 0x0f,
242 	I2400M_RO_CIN_SHIFT  = 4,
243 	I2400M_RO_FBN        = 0x07ff,
244 	I2400M_RO_FBN_SHIFT  = 8,
245 	I2400M_RO_SN         = 0x07ff,
246 	I2400M_RO_SN_SHIFT   = 21,
247 };
248 
249 enum i2400m_ro_type {
250 	I2400M_RO_TYPE_RESET = 0,
251 	I2400M_RO_TYPE_PACKET,
252 	I2400M_RO_TYPE_WS,
253 	I2400M_RO_TYPE_PACKET_WS,
254 };
255 
256 
257 /* Misc constants */
258 enum {
259 	I2400M_PL_ALIGN = 16,	/* Payload data size alignment */
260 	I2400M_PL_SIZE_MAX = 0x3EFF,
261 	I2400M_MAX_PLS_IN_MSG = 60,
262 	/* protocol barkers: sync sequences; for notifications they
263 	 * are sent in groups of four. */
264 	I2400M_H2D_PREVIEW_BARKER = 0xcafe900d,
265 	I2400M_COLD_RESET_BARKER = 0xc01dc01d,
266 	I2400M_WARM_RESET_BARKER = 0x50f750f7,
267 	I2400M_NBOOT_BARKER = 0xdeadbeef,
268 	I2400M_SBOOT_BARKER = 0x0ff1c1a1,
269 	I2400M_SBOOT_BARKER_6050 = 0x80000001,
270 	I2400M_ACK_BARKER = 0xfeedbabe,
271 	I2400M_D2H_MSG_BARKER = 0xbeefbabe,
272 };
273 
274 
275 /*
276  * Hardware payload descriptor
277  *
278  * Bitfields encoded in a struct to enforce typing semantics.
279  *
280  * Look in rx.c and tx.c for a full description of the format.
281  */
282 struct i2400m_pld {
283 	__le32 val;
284 } __attribute__ ((packed));
285 
286 #define I2400M_PLD_SIZE_MASK 0x00003fff
287 #define I2400M_PLD_TYPE_SHIFT 16
288 #define I2400M_PLD_TYPE_MASK 0x000f0000
289 
290 /*
291  * Header for a TX message or RX message
292  *
293  * @barker: preamble
294  * @size: used for management of the FIFO queue buffer; before
295  *     sending, this is converted to be a real preamble. This
296  *     indicates the real size of the TX message that starts at this
297  *     point. If the highest bit is set, then this message is to be
298  *     skipped.
299  * @sequence: sequence number of this message
300  * @offset: offset where the message itself starts -- see the comments
301  *     in the file header about message header and payload descriptor
302  *     alignment.
303  * @num_pls: number of payloads in this message
304  * @padding: amount of padding bytes at the end of the message to make
305  *           it be of block-size aligned
306  *
307  * Look in rx.c and tx.c for a full description of the format.
308  */
309 struct i2400m_msg_hdr {
310 	union {
311 		__le32 barker;
312 		__u32 size;	/* same size type as barker!! */
313 	};
314 	union {
315 		__le32 sequence;
316 		__u32 offset;	/* same size type as barker!! */
317 	};
318 	__le16 num_pls;
319 	__le16 rsv1;
320 	__le16 padding;
321 	__le16 rsv2;
322 	struct i2400m_pld pld[0];
323 } __attribute__ ((packed));
324 
325 
326 
327 /*
328  * L3/L4 control protocol
329  */
330 
331 enum {
332 	/* Interface version */
333 	I2400M_L3L4_VERSION             = 0x0100,
334 };
335 
336 /* Message types */
337 enum i2400m_mt {
338 	I2400M_MT_RESERVED              = 0x0000,
339 	I2400M_MT_INVALID               = 0xffff,
340 	I2400M_MT_REPORT_MASK		= 0x8000,
341 
342 	I2400M_MT_GET_SCAN_RESULT  	= 0x4202,
343 	I2400M_MT_SET_SCAN_PARAM   	= 0x4402,
344 	I2400M_MT_CMD_RF_CONTROL   	= 0x4602,
345 	I2400M_MT_CMD_SCAN         	= 0x4603,
346 	I2400M_MT_CMD_CONNECT      	= 0x4604,
347 	I2400M_MT_CMD_DISCONNECT   	= 0x4605,
348 	I2400M_MT_CMD_EXIT_IDLE   	= 0x4606,
349 	I2400M_MT_GET_LM_VERSION   	= 0x5201,
350 	I2400M_MT_GET_DEVICE_INFO  	= 0x5202,
351 	I2400M_MT_GET_LINK_STATUS  	= 0x5203,
352 	I2400M_MT_GET_STATISTICS   	= 0x5204,
353 	I2400M_MT_GET_STATE        	= 0x5205,
354 	I2400M_MT_GET_MEDIA_STATUS	= 0x5206,
355 	I2400M_MT_SET_INIT_CONFIG	= 0x5404,
356 	I2400M_MT_CMD_INIT	        = 0x5601,
357 	I2400M_MT_CMD_TERMINATE		= 0x5602,
358 	I2400M_MT_CMD_MODE_OF_OP	= 0x5603,
359 	I2400M_MT_CMD_RESET_DEVICE	= 0x5604,
360 	I2400M_MT_CMD_MONITOR_CONTROL   = 0x5605,
361 	I2400M_MT_CMD_ENTER_POWERSAVE   = 0x5606,
362 	I2400M_MT_GET_TLS_OPERATION_RESULT = 0x6201,
363 	I2400M_MT_SET_EAP_SUCCESS       = 0x6402,
364 	I2400M_MT_SET_EAP_FAIL          = 0x6403,
365 	I2400M_MT_SET_EAP_KEY          	= 0x6404,
366 	I2400M_MT_CMD_SEND_EAP_RESPONSE = 0x6602,
367 	I2400M_MT_REPORT_SCAN_RESULT    = 0xc002,
368 	I2400M_MT_REPORT_STATE		= 0xd002,
369 	I2400M_MT_REPORT_POWERSAVE_READY = 0xd005,
370 	I2400M_MT_REPORT_EAP_REQUEST    = 0xe002,
371 	I2400M_MT_REPORT_EAP_RESTART    = 0xe003,
372 	I2400M_MT_REPORT_ALT_ACCEPT    	= 0xe004,
373 	I2400M_MT_REPORT_KEY_REQUEST 	= 0xe005,
374 };
375 
376 
377 /*
378  * Message Ack Status codes
379  *
380  * When a message is replied-to, this status is reported.
381  */
382 enum i2400m_ms {
383 	I2400M_MS_DONE_OK                  = 0,
384 	I2400M_MS_DONE_IN_PROGRESS         = 1,
385 	I2400M_MS_INVALID_OP               = 2,
386 	I2400M_MS_BAD_STATE                = 3,
387 	I2400M_MS_ILLEGAL_VALUE            = 4,
388 	I2400M_MS_MISSING_PARAMS           = 5,
389 	I2400M_MS_VERSION_ERROR            = 6,
390 	I2400M_MS_ACCESSIBILITY_ERROR      = 7,
391 	I2400M_MS_BUSY                     = 8,
392 	I2400M_MS_CORRUPTED_TLV            = 9,
393 	I2400M_MS_UNINITIALIZED            = 10,
394 	I2400M_MS_UNKNOWN_ERROR            = 11,
395 	I2400M_MS_PRODUCTION_ERROR         = 12,
396 	I2400M_MS_NO_RF                    = 13,
397 	I2400M_MS_NOT_READY_FOR_POWERSAVE  = 14,
398 	I2400M_MS_THERMAL_CRITICAL         = 15,
399 	I2400M_MS_MAX
400 };
401 
402 
403 /**
404  * i2400m_tlv - enumeration of the different types of TLVs
405  *
406  * TLVs stand for type-length-value and are the header for a payload
407  * composed of almost anything. Each payload has a type assigned
408  * and a length.
409  */
410 enum i2400m_tlv {
411 	I2400M_TLV_L4_MESSAGE_VERSIONS = 129,
412 	I2400M_TLV_SYSTEM_STATE = 141,
413 	I2400M_TLV_MEDIA_STATUS = 161,
414 	I2400M_TLV_RF_OPERATION = 162,
415 	I2400M_TLV_RF_STATUS = 163,
416 	I2400M_TLV_DEVICE_RESET_TYPE = 132,
417 	I2400M_TLV_CONFIG_IDLE_PARAMETERS = 601,
418 	I2400M_TLV_CONFIG_IDLE_TIMEOUT = 611,
419 	I2400M_TLV_CONFIG_D2H_DATA_FORMAT = 614,
420 	I2400M_TLV_CONFIG_DL_HOST_REORDER = 615,
421 };
422 
423 
424 struct i2400m_tlv_hdr {
425 	__le16 type;
426 	__le16 length;		/* payload's */
427 	__u8   pl[0];
428 } __attribute__((packed));
429 
430 
431 struct i2400m_l3l4_hdr {
432 	__le16 type;
433 	__le16 length;		/* payload's */
434 	__le16 version;
435 	__le16 resv1;
436 	__le16 status;
437 	__le16 resv2;
438 	struct i2400m_tlv_hdr pl[0];
439 } __attribute__((packed));
440 
441 
442 /**
443  * i2400m_system_state - different states of the device
444  */
445 enum i2400m_system_state {
446 	I2400M_SS_UNINITIALIZED = 1,
447 	I2400M_SS_INIT,
448 	I2400M_SS_READY,
449 	I2400M_SS_SCAN,
450 	I2400M_SS_STANDBY,
451 	I2400M_SS_CONNECTING,
452 	I2400M_SS_WIMAX_CONNECTED,
453 	I2400M_SS_DATA_PATH_CONNECTED,
454 	I2400M_SS_IDLE,
455 	I2400M_SS_DISCONNECTING,
456 	I2400M_SS_OUT_OF_ZONE,
457 	I2400M_SS_SLEEPACTIVE,
458 	I2400M_SS_PRODUCTION,
459 	I2400M_SS_CONFIG,
460 	I2400M_SS_RF_OFF,
461 	I2400M_SS_RF_SHUTDOWN,
462 	I2400M_SS_DEVICE_DISCONNECT,
463 	I2400M_SS_MAX,
464 };
465 
466 
467 /**
468  * i2400m_tlv_system_state - report on the state of the system
469  *
470  * @state: see enum i2400m_system_state
471  */
472 struct i2400m_tlv_system_state {
473 	struct i2400m_tlv_hdr hdr;
474 	__le32 state;
475 } __attribute__((packed));
476 
477 
478 struct i2400m_tlv_l4_message_versions {
479 	struct i2400m_tlv_hdr hdr;
480 	__le16 major;
481 	__le16 minor;
482 	__le16 branch;
483 	__le16 reserved;
484 } __attribute__((packed));
485 
486 
487 struct i2400m_tlv_detailed_device_info {
488 	struct i2400m_tlv_hdr hdr;
489 	__u8 reserved1[400];
490 	__u8 mac_address[6];
491 	__u8 reserved2[2];
492 } __attribute__((packed));
493 
494 
495 enum i2400m_rf_switch_status {
496 	I2400M_RF_SWITCH_ON = 1,
497 	I2400M_RF_SWITCH_OFF = 2,
498 };
499 
500 struct i2400m_tlv_rf_switches_status {
501 	struct i2400m_tlv_hdr hdr;
502 	__u8 sw_rf_switch;	/* 1 ON, 2 OFF */
503 	__u8 hw_rf_switch;	/* 1 ON, 2 OFF */
504 	__u8 reserved[2];
505 } __attribute__((packed));
506 
507 
508 enum {
509 	i2400m_rf_operation_on = 1,
510 	i2400m_rf_operation_off = 2
511 };
512 
513 struct i2400m_tlv_rf_operation {
514 	struct i2400m_tlv_hdr hdr;
515 	__le32 status;	/* 1 ON, 2 OFF */
516 } __attribute__((packed));
517 
518 
519 enum i2400m_tlv_reset_type {
520 	I2400M_RESET_TYPE_COLD = 1,
521 	I2400M_RESET_TYPE_WARM
522 };
523 
524 struct i2400m_tlv_device_reset_type {
525 	struct i2400m_tlv_hdr hdr;
526 	__le32 reset_type;
527 } __attribute__((packed));
528 
529 
530 struct i2400m_tlv_config_idle_parameters {
531 	struct i2400m_tlv_hdr hdr;
532 	__le32 idle_timeout;	/* 100 to 300000 ms [5min], 100 increments
533 				 * 0 disabled */
534 	__le32 idle_paging_interval;	/* frames */
535 } __attribute__((packed));
536 
537 
538 enum i2400m_media_status {
539 	I2400M_MEDIA_STATUS_LINK_UP = 1,
540 	I2400M_MEDIA_STATUS_LINK_DOWN,
541 	I2400M_MEDIA_STATUS_LINK_RENEW,
542 };
543 
544 struct i2400m_tlv_media_status {
545 	struct i2400m_tlv_hdr hdr;
546 	__le32 media_status;
547 } __attribute__((packed));
548 
549 
550 /* New in v1.4 */
551 struct i2400m_tlv_config_idle_timeout {
552 	struct i2400m_tlv_hdr hdr;
553 	__le32 timeout;	/* 100 to 300000 ms [5min], 100 increments
554 			 * 0 disabled */
555 } __attribute__((packed));
556 
557 /* New in v1.4 -- for backward compat, will be removed */
558 struct i2400m_tlv_config_d2h_data_format {
559 	struct i2400m_tlv_hdr hdr;
560 	__u8 format; 		/* 0 old format, 1 enhanced */
561 	__u8 reserved[3];
562 } __attribute__((packed));
563 
564 /* New in v1.4 */
565 struct i2400m_tlv_config_dl_host_reorder {
566 	struct i2400m_tlv_hdr hdr;
567 	__u8 reorder; 		/* 0 disabled, 1 enabled */
568 	__u8 reserved[3];
569 } __attribute__((packed));
570 
571 
572 #endif /* #ifndef __LINUX__WIMAX__I2400M_H__ */
573