2 * Intel Wireless WiMax Connection 2400m
3 * Host-Device protocol interface definitions
6 * Copyright (C) 2007-2008 Intel Corporation. All rights reserved.
8 * Redistribution and use in source and binary forms, with or without
9 * modification, are permitted provided that the following conditions
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
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.
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.
35 * Intel Corporation <linux-wimax@intel.com>
36 * Inaky Perez-Gonzalez <inaky.perez-gonzalez@intel.com>
37 * - Initial implementation
40 * This header defines the data structures and constants used to
41 * communicate with the device.
43 * BOOTMODE/BOOTROM/FIRMWARE UPLOAD PROTOCOL
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
49 * The BCF data structure is for the firmware file header.
52 * THE DATA / CONTROL PROTOCOL
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.
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
65 * The term L3L4 refers to Layer 3 (the device), Layer 4 (the
66 * driver/host software).
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".
73 * Each message is composed of:
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.
85 * All integers are represented as Little Endian.
87 * - REQUESTS AND EVENTS
89 * The requests can be clasified as follows:
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.
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.
102 * EVENT: asynchronous messages sent from the device, maybe as a
103 * consequence of previous COMMANDs but disassociated from
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
111 * The different requests and their formats are described below:
113 * I2400M_MT_* Message types
114 * I2400M_MS_* Message status (for replies, events)
117 * data types are named 'struct i2400m_msg_OPNAME', OPNAME matching the
121 #ifndef __LINUX__WIMAX__I2400M_H__
122 #define __LINUX__WIMAX__I2400M_H__
124 #include <linux/types.h>
128 * Host Device Interface (HDI) common to all busses
131 /* Boot-mode (firmware upload mode) commands */
133 /* Header for the firmware file */
134 struct i2400m_bcf_hdr
{
137 __le32 header_version
;
139 __le32 module_vendor
;
140 __le32 date
; /* BCD YYYMMDD */
142 __le32 key_size
; /* in dwords */
143 __le32 modulus_size
; /* in dwords */
144 __le32 exponent_size
; /* in dwords */
146 } __attribute__ ((packed
));
148 /* Boot mode opcodes */
149 enum i2400m_brh_opcode
{
151 I2400M_BRH_WRITE
= 2,
153 I2400M_BRH_SIGNED_JUMP
= 8,
154 I2400M_BRH_HASH_PAYLOAD_ONLY
= 9,
157 /* Boot mode command masks and stuff */
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,
171 /* Constants for bcf->module_id */
172 enum i2400m_bcf_mod_id
{
173 /* Firmware file carries its own pokes -- pokes are a set of
174 * magical values that have to be written in certain memory
175 * addresses to get the device up and ready for firmware
176 * download when it is in non-signed boot mode. */
177 I2400M_BCF_MOD_ID_POKES
= 0x000000001,
182 * i2400m_bootrom_header - Header for a boot-mode command
184 * @cmd: the above command descriptor
185 * @target_addr: where on the device memory should the action be performed.
186 * @data_size: for read/write, amount of data to be read/written
187 * @block_checksum: checksum value (if applicable)
188 * @payload: the beginning of data attached to this header
190 struct i2400m_bootrom_header
{
191 __le32 command
; /* Compose with enum i2400_brh */
194 __le32 block_checksum
;
196 } __attribute__ ((packed
));
200 * Data / control protocol
203 /* Packet types for the host-device interface */
207 I2400M_PT_TRACE
, /* For device debug */
208 I2400M_PT_RESET_WARM
, /* device reset */
209 I2400M_PT_RESET_COLD
, /* USB[transport] reset, like reconnect */
215 * Payload for a data packet
217 * This is prefixed to each and every outgoing DATA type.
219 struct i2400m_pl_data_hdr
{
221 } __attribute__((packed
));
226 I2400M_PL_PAD
= 16, /* Payload data size alignment */
227 I2400M_PL_SIZE_MAX
= 0x3EFF,
228 I2400M_MAX_PLS_IN_MSG
= 60,
229 /* protocol barkers: sync sequences; for notifications they
230 * are sent in groups of four. */
231 I2400M_H2D_PREVIEW_BARKER
= 0xcafe900d,
232 I2400M_COLD_RESET_BARKER
= 0xc01dc01d,
233 I2400M_WARM_RESET_BARKER
= 0x50f750f7,
234 I2400M_NBOOT_BARKER
= 0xdeadbeef,
235 I2400M_SBOOT_BARKER
= 0x0ff1c1a1,
236 I2400M_ACK_BARKER
= 0xfeedbabe,
237 I2400M_D2H_MSG_BARKER
= 0xbeefbabe,
242 * Hardware payload descriptor
244 * Bitfields encoded in a struct to enforce typing semantics.
246 * Look in rx.c and tx.c for a full description of the format.
250 } __attribute__ ((packed
));
252 #define I2400M_PLD_SIZE_MASK 0x00003fff
253 #define I2400M_PLD_TYPE_SHIFT 16
254 #define I2400M_PLD_TYPE_MASK 0x000f0000
257 * Header for a TX message or RX message
260 * @size: used for management of the FIFO queue buffer; before
261 * sending, this is converted to be a real preamble. This
262 * indicates the real size of the TX message that starts at this
263 * point. If the highest bit is set, then this message is to be
265 * @sequence: sequence number of this message
266 * @offset: offset where the message itself starts -- see the comments
267 * in the file header about message header and payload descriptor
269 * @num_pls: number of payloads in this message
270 * @padding: amount of padding bytes at the end of the message to make
271 * it be of block-size aligned
273 * Look in rx.c and tx.c for a full description of the format.
275 struct i2400m_msg_hdr
{
278 __u32 size
; /* same size type as barker!! */
282 __u32 offset
; /* same size type as barker!! */
288 struct i2400m_pld pld
[0];
289 } __attribute__ ((packed
));
294 * L3/L4 control protocol
298 /* Interface version */
299 I2400M_L3L4_VERSION
= 0x0100,
304 I2400M_MT_RESERVED
= 0x0000,
305 I2400M_MT_INVALID
= 0xffff,
306 I2400M_MT_REPORT_MASK
= 0x8000,
308 I2400M_MT_GET_SCAN_RESULT
= 0x4202,
309 I2400M_MT_SET_SCAN_PARAM
= 0x4402,
310 I2400M_MT_CMD_RF_CONTROL
= 0x4602,
311 I2400M_MT_CMD_SCAN
= 0x4603,
312 I2400M_MT_CMD_CONNECT
= 0x4604,
313 I2400M_MT_CMD_DISCONNECT
= 0x4605,
314 I2400M_MT_CMD_EXIT_IDLE
= 0x4606,
315 I2400M_MT_GET_LM_VERSION
= 0x5201,
316 I2400M_MT_GET_DEVICE_INFO
= 0x5202,
317 I2400M_MT_GET_LINK_STATUS
= 0x5203,
318 I2400M_MT_GET_STATISTICS
= 0x5204,
319 I2400M_MT_GET_STATE
= 0x5205,
320 I2400M_MT_GET_MEDIA_STATUS
= 0x5206,
321 I2400M_MT_SET_INIT_CONFIG
= 0x5404,
322 I2400M_MT_CMD_INIT
= 0x5601,
323 I2400M_MT_CMD_TERMINATE
= 0x5602,
324 I2400M_MT_CMD_MODE_OF_OP
= 0x5603,
325 I2400M_MT_CMD_RESET_DEVICE
= 0x5604,
326 I2400M_MT_CMD_MONITOR_CONTROL
= 0x5605,
327 I2400M_MT_CMD_ENTER_POWERSAVE
= 0x5606,
328 I2400M_MT_GET_TLS_OPERATION_RESULT
= 0x6201,
329 I2400M_MT_SET_EAP_SUCCESS
= 0x6402,
330 I2400M_MT_SET_EAP_FAIL
= 0x6403,
331 I2400M_MT_SET_EAP_KEY
= 0x6404,
332 I2400M_MT_CMD_SEND_EAP_RESPONSE
= 0x6602,
333 I2400M_MT_REPORT_SCAN_RESULT
= 0xc002,
334 I2400M_MT_REPORT_STATE
= 0xd002,
335 I2400M_MT_REPORT_POWERSAVE_READY
= 0xd005,
336 I2400M_MT_REPORT_EAP_REQUEST
= 0xe002,
337 I2400M_MT_REPORT_EAP_RESTART
= 0xe003,
338 I2400M_MT_REPORT_ALT_ACCEPT
= 0xe004,
339 I2400M_MT_REPORT_KEY_REQUEST
= 0xe005,
344 * Message Ack Status codes
346 * When a message is replied-to, this status is reported.
349 I2400M_MS_DONE_OK
= 0,
350 I2400M_MS_DONE_IN_PROGRESS
= 1,
351 I2400M_MS_INVALID_OP
= 2,
352 I2400M_MS_BAD_STATE
= 3,
353 I2400M_MS_ILLEGAL_VALUE
= 4,
354 I2400M_MS_MISSING_PARAMS
= 5,
355 I2400M_MS_VERSION_ERROR
= 6,
356 I2400M_MS_ACCESSIBILITY_ERROR
= 7,
358 I2400M_MS_CORRUPTED_TLV
= 9,
359 I2400M_MS_UNINITIALIZED
= 10,
360 I2400M_MS_UNKNOWN_ERROR
= 11,
361 I2400M_MS_PRODUCTION_ERROR
= 12,
362 I2400M_MS_NO_RF
= 13,
363 I2400M_MS_NOT_READY_FOR_POWERSAVE
= 14,
364 I2400M_MS_THERMAL_CRITICAL
= 15,
370 * i2400m_tlv - enumeration of the different types of TLVs
372 * TLVs stand for type-length-value and are the header for a payload
373 * composed of almost anything. Each payload has a type assigned
377 I2400M_TLV_L4_MESSAGE_VERSIONS
= 129,
378 I2400M_TLV_SYSTEM_STATE
= 141,
379 I2400M_TLV_MEDIA_STATUS
= 161,
380 I2400M_TLV_RF_OPERATION
= 162,
381 I2400M_TLV_RF_STATUS
= 163,
382 I2400M_TLV_DEVICE_RESET_TYPE
= 132,
383 I2400M_TLV_CONFIG_IDLE_PARAMETERS
= 601,
387 struct i2400m_tlv_hdr
{
389 __le16 length
; /* payload's */
391 } __attribute__((packed
));
394 struct i2400m_l3l4_hdr
{
396 __le16 length
; /* payload's */
401 struct i2400m_tlv_hdr pl
[0];
402 } __attribute__((packed
));
406 * i2400m_system_state - different states of the device
408 enum i2400m_system_state
{
409 I2400M_SS_UNINITIALIZED
= 1,
414 I2400M_SS_CONNECTING
,
415 I2400M_SS_WIMAX_CONNECTED
,
416 I2400M_SS_DATA_PATH_CONNECTED
,
418 I2400M_SS_DISCONNECTING
,
419 I2400M_SS_OUT_OF_ZONE
,
420 I2400M_SS_SLEEPACTIVE
,
421 I2400M_SS_PRODUCTION
,
424 I2400M_SS_RF_SHUTDOWN
,
425 I2400M_SS_DEVICE_DISCONNECT
,
431 * i2400m_tlv_system_state - report on the state of the system
433 * @state: see enum i2400m_system_state
435 struct i2400m_tlv_system_state
{
436 struct i2400m_tlv_hdr hdr
;
438 } __attribute__((packed
));
441 struct i2400m_tlv_l4_message_versions
{
442 struct i2400m_tlv_hdr hdr
;
447 } __attribute__((packed
));
450 struct i2400m_tlv_detailed_device_info
{
451 struct i2400m_tlv_hdr hdr
;
455 } __attribute__((packed
));
458 enum i2400m_rf_switch_status
{
459 I2400M_RF_SWITCH_ON
= 1,
460 I2400M_RF_SWITCH_OFF
= 2,
463 struct i2400m_tlv_rf_switches_status
{
464 struct i2400m_tlv_hdr hdr
;
465 __u8 sw_rf_switch
; /* 1 ON, 2 OFF */
466 __u8 hw_rf_switch
; /* 1 ON, 2 OFF */
468 } __attribute__((packed
));
472 i2400m_rf_operation_on
= 1,
473 i2400m_rf_operation_off
= 2
476 struct i2400m_tlv_rf_operation
{
477 struct i2400m_tlv_hdr hdr
;
478 __le32 status
; /* 1 ON, 2 OFF */
479 } __attribute__((packed
));
482 enum i2400m_tlv_reset_type
{
483 I2400M_RESET_TYPE_COLD
= 1,
484 I2400M_RESET_TYPE_WARM
487 struct i2400m_tlv_device_reset_type
{
488 struct i2400m_tlv_hdr hdr
;
490 } __attribute__((packed
));
493 struct i2400m_tlv_config_idle_parameters
{
494 struct i2400m_tlv_hdr hdr
;
495 __le32 idle_timeout
; /* 100 to 300000 ms [5min], 100 increments
497 __le32 idle_paging_interval
; /* frames */
498 } __attribute__((packed
));
501 enum i2400m_media_status
{
502 I2400M_MEDIA_STATUS_LINK_UP
= 1,
503 I2400M_MEDIA_STATUS_LINK_DOWN
,
504 I2400M_MEDIA_STATUS_LINK_RENEW
,
507 struct i2400m_tlv_media_status
{
508 struct i2400m_tlv_hdr hdr
;
510 } __attribute__((packed
));
512 #endif /* #ifndef __LINUX__WIMAX__I2400M_H__ */