2 * Copyright IBM Corp. 2002, 2009
4 * Author(s): Martin Schwidefsky (schwidefsky@de.ibm.com)
5 * Cornelia Huck (cornelia.huck@de.ibm.com)
7 #include <linux/module.h>
8 #include <linux/init.h>
9 #include <linux/errno.h>
10 #include <linux/slab.h>
11 #include <linux/list.h>
12 #include <linux/device.h>
13 #include <linux/delay.h>
15 #include <asm/ccwdev.h>
16 #include <asm/idals.h>
17 #include <asm/chpid.h>
21 #include "cio_debug.h"
28 * ccw_device_set_options_mask() - set some options and unset the rest
29 * @cdev: device for which the options are to be set
30 * @flags: options to be set
32 * All flags specified in @flags are set, all flags not specified in @flags
35 * %0 on success, -%EINVAL on an invalid flag combination.
37 int ccw_device_set_options_mask(struct ccw_device
*cdev
, unsigned long flags
)
40 * The flag usage is mutal exclusive ...
42 if ((flags
& CCWDEV_EARLY_NOTIFICATION
) &&
43 (flags
& CCWDEV_REPORT_ALL
))
45 cdev
->private->options
.fast
= (flags
& CCWDEV_EARLY_NOTIFICATION
) != 0;
46 cdev
->private->options
.repall
= (flags
& CCWDEV_REPORT_ALL
) != 0;
47 cdev
->private->options
.pgroup
= (flags
& CCWDEV_DO_PATHGROUP
) != 0;
48 cdev
->private->options
.force
= (flags
& CCWDEV_ALLOW_FORCE
) != 0;
53 * ccw_device_set_options() - set some options
54 * @cdev: device for which the options are to be set
55 * @flags: options to be set
57 * All flags specified in @flags are set, the remainder is left untouched.
59 * %0 on success, -%EINVAL if an invalid flag combination would ensue.
61 int ccw_device_set_options(struct ccw_device
*cdev
, unsigned long flags
)
64 * The flag usage is mutal exclusive ...
66 if (((flags
& CCWDEV_EARLY_NOTIFICATION
) &&
67 (flags
& CCWDEV_REPORT_ALL
)) ||
68 ((flags
& CCWDEV_EARLY_NOTIFICATION
) &&
69 cdev
->private->options
.repall
) ||
70 ((flags
& CCWDEV_REPORT_ALL
) &&
71 cdev
->private->options
.fast
))
73 cdev
->private->options
.fast
|= (flags
& CCWDEV_EARLY_NOTIFICATION
) != 0;
74 cdev
->private->options
.repall
|= (flags
& CCWDEV_REPORT_ALL
) != 0;
75 cdev
->private->options
.pgroup
|= (flags
& CCWDEV_DO_PATHGROUP
) != 0;
76 cdev
->private->options
.force
|= (flags
& CCWDEV_ALLOW_FORCE
) != 0;
81 * ccw_device_clear_options() - clear some options
82 * @cdev: device for which the options are to be cleared
83 * @flags: options to be cleared
85 * All flags specified in @flags are cleared, the remainder is left untouched.
87 void ccw_device_clear_options(struct ccw_device
*cdev
, unsigned long flags
)
89 cdev
->private->options
.fast
&= (flags
& CCWDEV_EARLY_NOTIFICATION
) == 0;
90 cdev
->private->options
.repall
&= (flags
& CCWDEV_REPORT_ALL
) == 0;
91 cdev
->private->options
.pgroup
&= (flags
& CCWDEV_DO_PATHGROUP
) == 0;
92 cdev
->private->options
.force
&= (flags
& CCWDEV_ALLOW_FORCE
) == 0;
96 * ccw_device_clear() - terminate I/O request processing
97 * @cdev: target ccw device
98 * @intparm: interruption parameter; value is only used if no I/O is
99 * outstanding, otherwise the intparm associated with the I/O request
102 * ccw_device_clear() calls csch on @cdev's subchannel.
105 * -%ENODEV on device not operational,
106 * -%EINVAL on invalid device state.
108 * Interrupts disabled, ccw device lock held
110 int ccw_device_clear(struct ccw_device
*cdev
, unsigned long intparm
)
112 struct subchannel
*sch
;
115 if (!cdev
|| !cdev
->dev
.parent
)
117 sch
= to_subchannel(cdev
->dev
.parent
);
118 if (!sch
->schib
.pmcw
.ena
)
120 if (cdev
->private->state
== DEV_STATE_NOT_OPER
)
122 if (cdev
->private->state
!= DEV_STATE_ONLINE
&&
123 cdev
->private->state
!= DEV_STATE_W4SENSE
)
126 ret
= cio_clear(sch
);
128 cdev
->private->intparm
= intparm
;
133 * ccw_device_start_key() - start a s390 channel program with key
134 * @cdev: target ccw device
135 * @cpa: logical start address of channel program
136 * @intparm: user specific interruption parameter; will be presented back to
137 * @cdev's interrupt handler. Allows a device driver to associate
138 * the interrupt with a particular I/O request.
139 * @lpm: defines the channel path to be used for a specific I/O request. A
140 * value of 0 will make cio use the opm.
141 * @key: storage key to be used for the I/O
142 * @flags: additional flags; defines the action to be performed for I/O
145 * Start a S/390 channel program. When the interrupt arrives, the
146 * IRQ handler is called, either immediately, delayed (dev-end missing,
147 * or sense required) or never (no IRQ handler registered).
149 * %0, if the operation was successful;
150 * -%EBUSY, if the device is busy, or status pending;
151 * -%EACCES, if no path specified in @lpm is operational;
152 * -%ENODEV, if the device is not operational.
154 * Interrupts disabled, ccw device lock held
156 int ccw_device_start_key(struct ccw_device
*cdev
, struct ccw1
*cpa
,
157 unsigned long intparm
, __u8 lpm
, __u8 key
,
160 struct subchannel
*sch
;
163 if (!cdev
|| !cdev
->dev
.parent
)
165 sch
= to_subchannel(cdev
->dev
.parent
);
166 if (!sch
->schib
.pmcw
.ena
)
168 if (cdev
->private->state
== DEV_STATE_NOT_OPER
)
170 if (cdev
->private->state
== DEV_STATE_VERIFY
) {
171 /* Remember to fake irb when finished. */
172 if (!cdev
->private->flags
.fake_irb
) {
173 cdev
->private->flags
.fake_irb
= 1;
174 cdev
->private->intparm
= intparm
;
177 /* There's already a fake I/O around. */
180 if (cdev
->private->state
!= DEV_STATE_ONLINE
||
181 ((sch
->schib
.scsw
.cmd
.stctl
& SCSW_STCTL_PRIM_STATUS
) &&
182 !(sch
->schib
.scsw
.cmd
.stctl
& SCSW_STCTL_SEC_STATUS
)) ||
183 cdev
->private->flags
.doverify
)
185 ret
= cio_set_options (sch
, flags
);
188 /* Adjust requested path mask to excluded varied off paths. */
194 ret
= cio_start_key (sch
, cpa
, lpm
, key
);
197 cdev
->private->intparm
= intparm
;
201 dev_fsm_event(cdev
, DEV_EVENT_VERIFY
);
208 * ccw_device_start_timeout_key() - start a s390 channel program with timeout and key
209 * @cdev: target ccw device
210 * @cpa: logical start address of channel program
211 * @intparm: user specific interruption parameter; will be presented back to
212 * @cdev's interrupt handler. Allows a device driver to associate
213 * the interrupt with a particular I/O request.
214 * @lpm: defines the channel path to be used for a specific I/O request. A
215 * value of 0 will make cio use the opm.
216 * @key: storage key to be used for the I/O
217 * @flags: additional flags; defines the action to be performed for I/O
219 * @expires: timeout value in jiffies
221 * Start a S/390 channel program. When the interrupt arrives, the
222 * IRQ handler is called, either immediately, delayed (dev-end missing,
223 * or sense required) or never (no IRQ handler registered).
224 * This function notifies the device driver if the channel program has not
225 * completed during the time specified by @expires. If a timeout occurs, the
226 * channel program is terminated via xsch, hsch or csch, and the device's
227 * interrupt handler will be called with an irb containing ERR_PTR(-%ETIMEDOUT).
229 * %0, if the operation was successful;
230 * -%EBUSY, if the device is busy, or status pending;
231 * -%EACCES, if no path specified in @lpm is operational;
232 * -%ENODEV, if the device is not operational.
234 * Interrupts disabled, ccw device lock held
236 int ccw_device_start_timeout_key(struct ccw_device
*cdev
, struct ccw1
*cpa
,
237 unsigned long intparm
, __u8 lpm
, __u8 key
,
238 unsigned long flags
, int expires
)
244 ccw_device_set_timeout(cdev
, expires
);
245 ret
= ccw_device_start_key(cdev
, cpa
, intparm
, lpm
, key
, flags
);
247 ccw_device_set_timeout(cdev
, 0);
252 * ccw_device_start() - start a s390 channel program
253 * @cdev: target ccw device
254 * @cpa: logical start address of channel program
255 * @intparm: user specific interruption parameter; will be presented back to
256 * @cdev's interrupt handler. Allows a device driver to associate
257 * the interrupt with a particular I/O request.
258 * @lpm: defines the channel path to be used for a specific I/O request. A
259 * value of 0 will make cio use the opm.
260 * @flags: additional flags; defines the action to be performed for I/O
263 * Start a S/390 channel program. When the interrupt arrives, the
264 * IRQ handler is called, either immediately, delayed (dev-end missing,
265 * or sense required) or never (no IRQ handler registered).
267 * %0, if the operation was successful;
268 * -%EBUSY, if the device is busy, or status pending;
269 * -%EACCES, if no path specified in @lpm is operational;
270 * -%ENODEV, if the device is not operational.
272 * Interrupts disabled, ccw device lock held
274 int ccw_device_start(struct ccw_device
*cdev
, struct ccw1
*cpa
,
275 unsigned long intparm
, __u8 lpm
, unsigned long flags
)
277 return ccw_device_start_key(cdev
, cpa
, intparm
, lpm
,
278 PAGE_DEFAULT_KEY
, flags
);
282 * ccw_device_start_timeout() - start a s390 channel program with timeout
283 * @cdev: target ccw device
284 * @cpa: logical start address of channel program
285 * @intparm: user specific interruption parameter; will be presented back to
286 * @cdev's interrupt handler. Allows a device driver to associate
287 * the interrupt with a particular I/O request.
288 * @lpm: defines the channel path to be used for a specific I/O request. A
289 * value of 0 will make cio use the opm.
290 * @flags: additional flags; defines the action to be performed for I/O
292 * @expires: timeout value in jiffies
294 * Start a S/390 channel program. When the interrupt arrives, the
295 * IRQ handler is called, either immediately, delayed (dev-end missing,
296 * or sense required) or never (no IRQ handler registered).
297 * This function notifies the device driver if the channel program has not
298 * completed during the time specified by @expires. If a timeout occurs, the
299 * channel program is terminated via xsch, hsch or csch, and the device's
300 * interrupt handler will be called with an irb containing ERR_PTR(-%ETIMEDOUT).
302 * %0, if the operation was successful;
303 * -%EBUSY, if the device is busy, or status pending;
304 * -%EACCES, if no path specified in @lpm is operational;
305 * -%ENODEV, if the device is not operational.
307 * Interrupts disabled, ccw device lock held
309 int ccw_device_start_timeout(struct ccw_device
*cdev
, struct ccw1
*cpa
,
310 unsigned long intparm
, __u8 lpm
,
311 unsigned long flags
, int expires
)
313 return ccw_device_start_timeout_key(cdev
, cpa
, intparm
, lpm
,
314 PAGE_DEFAULT_KEY
, flags
,
320 * ccw_device_halt() - halt I/O request processing
321 * @cdev: target ccw device
322 * @intparm: interruption parameter; value is only used if no I/O is
323 * outstanding, otherwise the intparm associated with the I/O request
326 * ccw_device_halt() calls hsch on @cdev's subchannel.
329 * -%ENODEV on device not operational,
330 * -%EINVAL on invalid device state,
331 * -%EBUSY on device busy or interrupt pending.
333 * Interrupts disabled, ccw device lock held
335 int ccw_device_halt(struct ccw_device
*cdev
, unsigned long intparm
)
337 struct subchannel
*sch
;
340 if (!cdev
|| !cdev
->dev
.parent
)
342 sch
= to_subchannel(cdev
->dev
.parent
);
343 if (!sch
->schib
.pmcw
.ena
)
345 if (cdev
->private->state
== DEV_STATE_NOT_OPER
)
347 if (cdev
->private->state
!= DEV_STATE_ONLINE
&&
348 cdev
->private->state
!= DEV_STATE_W4SENSE
)
353 cdev
->private->intparm
= intparm
;
358 * ccw_device_resume() - resume channel program execution
359 * @cdev: target ccw device
361 * ccw_device_resume() calls rsch on @cdev's subchannel.
364 * -%ENODEV on device not operational,
365 * -%EINVAL on invalid device state,
366 * -%EBUSY on device busy or interrupt pending.
368 * Interrupts disabled, ccw device lock held
370 int ccw_device_resume(struct ccw_device
*cdev
)
372 struct subchannel
*sch
;
374 if (!cdev
|| !cdev
->dev
.parent
)
376 sch
= to_subchannel(cdev
->dev
.parent
);
377 if (!sch
->schib
.pmcw
.ena
)
379 if (cdev
->private->state
== DEV_STATE_NOT_OPER
)
381 if (cdev
->private->state
!= DEV_STATE_ONLINE
||
382 !(sch
->schib
.scsw
.cmd
.actl
& SCSW_ACTL_SUSPENDED
))
384 return cio_resume(sch
);
388 * Pass interrupt to device driver.
391 ccw_device_call_handler(struct ccw_device
*cdev
)
393 struct subchannel
*sch
;
397 sch
= to_subchannel(cdev
->dev
.parent
);
400 * we allow for the device action handler if .
401 * - we received ending status
402 * - the action handler requested to see all interrupts
403 * - we received an intermediate status
404 * - fast notification was requested (primary status)
405 * - unsolicited interrupts
407 stctl
= scsw_stctl(&cdev
->private->irb
.scsw
);
408 ending_status
= (stctl
& SCSW_STCTL_SEC_STATUS
) ||
409 (stctl
== (SCSW_STCTL_ALERT_STATUS
| SCSW_STCTL_STATUS_PEND
)) ||
410 (stctl
== SCSW_STCTL_STATUS_PEND
);
411 if (!ending_status
&&
412 !cdev
->private->options
.repall
&&
413 !(stctl
& SCSW_STCTL_INTER_STATUS
) &&
414 !(cdev
->private->options
.fast
&&
415 (stctl
& SCSW_STCTL_PRIM_STATUS
)))
418 /* Clear pending timers for device driver initiated I/O. */
420 ccw_device_set_timeout(cdev
, 0);
422 * Now we are ready to call the device driver interrupt handler.
425 cdev
->handler(cdev
, cdev
->private->intparm
,
426 &cdev
->private->irb
);
429 * Clear the old and now useless interrupt response block.
431 memset(&cdev
->private->irb
, 0, sizeof(struct irb
));
437 * ccw_device_get_ciw() - Search for CIW command in extended sense data.
438 * @cdev: ccw device to inspect
439 * @ct: command type to look for
441 * During SenseID, command information words (CIWs) describing special
442 * commands available to the device may have been stored in the extended
443 * sense data. This function searches for CIWs of a specified command
444 * type in the extended sense data.
446 * %NULL if no extended sense data has been stored or if no CIW of the
447 * specified command type could be found,
448 * else a pointer to the CIW of the specified command type.
450 struct ciw
*ccw_device_get_ciw(struct ccw_device
*cdev
, __u32 ct
)
454 if (cdev
->private->flags
.esid
== 0)
456 for (ciw_cnt
= 0; ciw_cnt
< MAX_CIWS
; ciw_cnt
++)
457 if (cdev
->private->senseid
.ciw
[ciw_cnt
].ct
== ct
)
458 return cdev
->private->senseid
.ciw
+ ciw_cnt
;
463 * ccw_device_get_path_mask() - get currently available paths
464 * @cdev: ccw device to be queried
466 * %0 if no subchannel for the device is available,
467 * else the mask of currently available paths for the ccw device's subchannel.
469 __u8
ccw_device_get_path_mask(struct ccw_device
*cdev
)
471 struct subchannel
*sch
;
473 if (!cdev
->dev
.parent
)
476 sch
= to_subchannel(cdev
->dev
.parent
);
481 * Try to break the lock on a boxed device.
484 ccw_device_stlck(struct ccw_device
*cdev
)
488 struct subchannel
*sch
;
494 if (cdev
->drv
&& !cdev
->private->options
.force
)
497 sch
= to_subchannel(cdev
->dev
.parent
);
499 CIO_TRACE_EVENT(2, "stl lock");
500 CIO_TRACE_EVENT(2, dev_name(&cdev
->dev
));
502 buf
= kmalloc(32*sizeof(char), GFP_DMA
|GFP_KERNEL
);
505 buf2
= kmalloc(32*sizeof(char), GFP_DMA
|GFP_KERNEL
);
510 spin_lock_irqsave(sch
->lock
, flags
);
511 ret
= cio_enable_subchannel(sch
, (u32
)(addr_t
)sch
);
515 * Setup ccw. We chain an unconditional reserve and a release so we
516 * only break the lock.
518 cdev
->private->iccws
[0].cmd_code
= CCW_CMD_STLCK
;
519 cdev
->private->iccws
[0].cda
= (__u32
) __pa(buf
);
520 cdev
->private->iccws
[0].count
= 32;
521 cdev
->private->iccws
[0].flags
= CCW_FLAG_CC
;
522 cdev
->private->iccws
[1].cmd_code
= CCW_CMD_RELEASE
;
523 cdev
->private->iccws
[1].cda
= (__u32
) __pa(buf2
);
524 cdev
->private->iccws
[1].count
= 32;
525 cdev
->private->iccws
[1].flags
= 0;
526 ret
= cio_start(sch
, cdev
->private->iccws
, 0);
528 cio_disable_subchannel(sch
); //FIXME: return code?
531 cdev
->private->irb
.scsw
.cmd
.actl
|= SCSW_ACTL_START_PEND
;
532 spin_unlock_irqrestore(sch
->lock
, flags
);
533 wait_event(cdev
->private->wait_q
,
534 cdev
->private->irb
.scsw
.cmd
.actl
== 0);
535 spin_lock_irqsave(sch
->lock
, flags
);
536 cio_disable_subchannel(sch
); //FIXME: return code?
537 if ((cdev
->private->irb
.scsw
.cmd
.dstat
!=
538 (DEV_STAT_CHN_END
|DEV_STAT_DEV_END
)) ||
539 (cdev
->private->irb
.scsw
.cmd
.cstat
!= 0))
542 memset(&cdev
->private->irb
, 0, sizeof(struct irb
));
546 spin_unlock_irqrestore(sch
->lock
, flags
);
550 void *ccw_device_get_chp_desc(struct ccw_device
*cdev
, int chp_no
)
552 struct subchannel
*sch
;
555 sch
= to_subchannel(cdev
->dev
.parent
);
557 chpid
.id
= sch
->schib
.pmcw
.chpid
[chp_no
];
558 return chp_get_chp_desc(chpid
);
562 * ccw_device_get_id - obtain a ccw device id
563 * @cdev: device to obtain the id for
564 * @dev_id: where to fill in the values
566 void ccw_device_get_id(struct ccw_device
*cdev
, struct ccw_dev_id
*dev_id
)
568 *dev_id
= cdev
->private->dev_id
;
570 EXPORT_SYMBOL(ccw_device_get_id
);
573 * ccw_device_tm_start_key - perform start function
574 * @cdev: ccw device on which to perform the start function
575 * @tcw: transport-command word to be started
576 * @intparm: user defined parameter to be passed to the interrupt handler
577 * @lpm: mask of paths to use
578 * @key: storage key to use for storage access
580 * Start the tcw on the given ccw device. Return zero on success, non-zero
583 int ccw_device_tm_start_key(struct ccw_device
*cdev
, struct tcw
*tcw
,
584 unsigned long intparm
, u8 lpm
, u8 key
)
586 struct subchannel
*sch
;
589 sch
= to_subchannel(cdev
->dev
.parent
);
590 if (!sch
->schib
.pmcw
.ena
)
592 if (cdev
->private->state
!= DEV_STATE_ONLINE
)
594 /* Adjust requested path mask to excluded varied off paths. */
600 rc
= cio_tm_start_key(sch
, tcw
, lpm
, key
);
602 cdev
->private->intparm
= intparm
;
605 EXPORT_SYMBOL(ccw_device_tm_start_key
);
608 * ccw_device_tm_start_timeout_key - perform start function
609 * @cdev: ccw device on which to perform the start function
610 * @tcw: transport-command word to be started
611 * @intparm: user defined parameter to be passed to the interrupt handler
612 * @lpm: mask of paths to use
613 * @key: storage key to use for storage access
614 * @expires: time span in jiffies after which to abort request
616 * Start the tcw on the given ccw device. Return zero on success, non-zero
619 int ccw_device_tm_start_timeout_key(struct ccw_device
*cdev
, struct tcw
*tcw
,
620 unsigned long intparm
, u8 lpm
, u8 key
,
625 ccw_device_set_timeout(cdev
, expires
);
626 ret
= ccw_device_tm_start_key(cdev
, tcw
, intparm
, lpm
, key
);
628 ccw_device_set_timeout(cdev
, 0);
631 EXPORT_SYMBOL(ccw_device_tm_start_timeout_key
);
634 * ccw_device_tm_start - perform start function
635 * @cdev: ccw device on which to perform the start function
636 * @tcw: transport-command word to be started
637 * @intparm: user defined parameter to be passed to the interrupt handler
638 * @lpm: mask of paths to use
640 * Start the tcw on the given ccw device. Return zero on success, non-zero
643 int ccw_device_tm_start(struct ccw_device
*cdev
, struct tcw
*tcw
,
644 unsigned long intparm
, u8 lpm
)
646 return ccw_device_tm_start_key(cdev
, tcw
, intparm
, lpm
,
649 EXPORT_SYMBOL(ccw_device_tm_start
);
652 * ccw_device_tm_start_timeout - perform start function
653 * @cdev: ccw device on which to perform the start function
654 * @tcw: transport-command word to be started
655 * @intparm: user defined parameter to be passed to the interrupt handler
656 * @lpm: mask of paths to use
657 * @expires: time span in jiffies after which to abort request
659 * Start the tcw on the given ccw device. Return zero on success, non-zero
662 int ccw_device_tm_start_timeout(struct ccw_device
*cdev
, struct tcw
*tcw
,
663 unsigned long intparm
, u8 lpm
, int expires
)
665 return ccw_device_tm_start_timeout_key(cdev
, tcw
, intparm
, lpm
,
666 PAGE_DEFAULT_KEY
, expires
);
668 EXPORT_SYMBOL(ccw_device_tm_start_timeout
);
671 * ccw_device_tm_intrg - perform interrogate function
672 * @cdev: ccw device on which to perform the interrogate function
674 * Perform an interrogate function on the given ccw device. Return zero on
675 * success, non-zero otherwise.
677 int ccw_device_tm_intrg(struct ccw_device
*cdev
)
679 struct subchannel
*sch
= to_subchannel(cdev
->dev
.parent
);
681 if (!sch
->schib
.pmcw
.ena
)
683 if (cdev
->private->state
!= DEV_STATE_ONLINE
)
685 if (!scsw_is_tm(&sch
->schib
.scsw
) ||
686 !(scsw_actl(&sch
->schib
.scsw
) & SCSW_ACTL_START_PEND
))
688 return cio_tm_intrg(sch
);
690 EXPORT_SYMBOL(ccw_device_tm_intrg
);
692 // FIXME: these have to go:
695 _ccw_device_get_subchannel_number(struct ccw_device
*cdev
)
697 return cdev
->private->schid
.sch_no
;
701 MODULE_LICENSE("GPL");
702 EXPORT_SYMBOL(ccw_device_set_options_mask
);
703 EXPORT_SYMBOL(ccw_device_set_options
);
704 EXPORT_SYMBOL(ccw_device_clear_options
);
705 EXPORT_SYMBOL(ccw_device_clear
);
706 EXPORT_SYMBOL(ccw_device_halt
);
707 EXPORT_SYMBOL(ccw_device_resume
);
708 EXPORT_SYMBOL(ccw_device_start_timeout
);
709 EXPORT_SYMBOL(ccw_device_start
);
710 EXPORT_SYMBOL(ccw_device_start_timeout_key
);
711 EXPORT_SYMBOL(ccw_device_start_key
);
712 EXPORT_SYMBOL(ccw_device_get_ciw
);
713 EXPORT_SYMBOL(ccw_device_get_path_mask
);
714 EXPORT_SYMBOL(_ccw_device_get_subchannel_number
);
715 EXPORT_SYMBOL_GPL(ccw_device_get_chp_desc
);