]> git.karo-electronics.de Git - mv-sheeva.git/blob - drivers/char/tpm/tpm.c
tpm: Adjust the durations if they are too small
[mv-sheeva.git] / drivers / char / tpm / tpm.c
1 /*
2  * Copyright (C) 2004 IBM Corporation
3  *
4  * Authors:
5  * Leendert van Doorn <leendert@watson.ibm.com>
6  * Dave Safford <safford@watson.ibm.com>
7  * Reiner Sailer <sailer@watson.ibm.com>
8  * Kylene Hall <kjhall@us.ibm.com>
9  *
10  * Maintained by: <tpmdd-devel@lists.sourceforge.net>
11  *
12  * Device driver for TCG/TCPA TPM (trusted platform module).
13  * Specifications at www.trustedcomputinggroup.org       
14  *
15  * This program is free software; you can redistribute it and/or
16  * modify it under the terms of the GNU General Public License as
17  * published by the Free Software Foundation, version 2 of the
18  * License.
19  * 
20  * Note, the TPM chip is not interrupt driven (only polling)
21  * and can have very long timeouts (minutes!). Hence the unusual
22  * calls to msleep.
23  *
24  */
25
26 #include <linux/poll.h>
27 #include <linux/slab.h>
28 #include <linux/mutex.h>
29 #include <linux/spinlock.h>
30
31 #include "tpm.h"
32
33 enum tpm_const {
34         TPM_MINOR = 224,        /* officially assigned */
35         TPM_BUFSIZE = 4096,
36         TPM_NUM_DEVICES = 256,
37 };
38
39 enum tpm_duration {
40         TPM_SHORT = 0,
41         TPM_MEDIUM = 1,
42         TPM_LONG = 2,
43         TPM_UNDEFINED,
44 };
45
46 #define TPM_MAX_ORDINAL 243
47 #define TPM_MAX_PROTECTED_ORDINAL 12
48 #define TPM_PROTECTED_ORDINAL_MASK 0xFF
49
50 /*
51  * Bug workaround - some TPM's don't flush the most
52  * recently changed pcr on suspend, so force the flush
53  * with an extend to the selected _unused_ non-volatile pcr.
54  */
55 static int tpm_suspend_pcr;
56 module_param_named(suspend_pcr, tpm_suspend_pcr, uint, 0644);
57 MODULE_PARM_DESC(suspend_pcr,
58                  "PCR to use for dummy writes to faciltate flush on suspend.");
59
60 static LIST_HEAD(tpm_chip_list);
61 static DEFINE_SPINLOCK(driver_lock);
62 static DECLARE_BITMAP(dev_mask, TPM_NUM_DEVICES);
63
64 /*
65  * Array with one entry per ordinal defining the maximum amount
66  * of time the chip could take to return the result.  The ordinal
67  * designation of short, medium or long is defined in a table in
68  * TCG Specification TPM Main Part 2 TPM Structures Section 17. The
69  * values of the SHORT, MEDIUM, and LONG durations are retrieved
70  * from the chip during initialization with a call to tpm_get_timeouts.
71  */
72 static const u8 tpm_protected_ordinal_duration[TPM_MAX_PROTECTED_ORDINAL] = {
73         TPM_UNDEFINED,          /* 0 */
74         TPM_UNDEFINED,
75         TPM_UNDEFINED,
76         TPM_UNDEFINED,
77         TPM_UNDEFINED,
78         TPM_UNDEFINED,          /* 5 */
79         TPM_UNDEFINED,
80         TPM_UNDEFINED,
81         TPM_UNDEFINED,
82         TPM_UNDEFINED,
83         TPM_SHORT,              /* 10 */
84         TPM_SHORT,
85 };
86
87 static const u8 tpm_ordinal_duration[TPM_MAX_ORDINAL] = {
88         TPM_UNDEFINED,          /* 0 */
89         TPM_UNDEFINED,
90         TPM_UNDEFINED,
91         TPM_UNDEFINED,
92         TPM_UNDEFINED,
93         TPM_UNDEFINED,          /* 5 */
94         TPM_UNDEFINED,
95         TPM_UNDEFINED,
96         TPM_UNDEFINED,
97         TPM_UNDEFINED,
98         TPM_SHORT,              /* 10 */
99         TPM_SHORT,
100         TPM_MEDIUM,
101         TPM_LONG,
102         TPM_LONG,
103         TPM_MEDIUM,             /* 15 */
104         TPM_SHORT,
105         TPM_SHORT,
106         TPM_MEDIUM,
107         TPM_LONG,
108         TPM_SHORT,              /* 20 */
109         TPM_SHORT,
110         TPM_MEDIUM,
111         TPM_MEDIUM,
112         TPM_MEDIUM,
113         TPM_SHORT,              /* 25 */
114         TPM_SHORT,
115         TPM_MEDIUM,
116         TPM_SHORT,
117         TPM_SHORT,
118         TPM_MEDIUM,             /* 30 */
119         TPM_LONG,
120         TPM_MEDIUM,
121         TPM_SHORT,
122         TPM_SHORT,
123         TPM_SHORT,              /* 35 */
124         TPM_MEDIUM,
125         TPM_MEDIUM,
126         TPM_UNDEFINED,
127         TPM_UNDEFINED,
128         TPM_MEDIUM,             /* 40 */
129         TPM_LONG,
130         TPM_MEDIUM,
131         TPM_SHORT,
132         TPM_SHORT,
133         TPM_SHORT,              /* 45 */
134         TPM_SHORT,
135         TPM_SHORT,
136         TPM_SHORT,
137         TPM_LONG,
138         TPM_MEDIUM,             /* 50 */
139         TPM_MEDIUM,
140         TPM_UNDEFINED,
141         TPM_UNDEFINED,
142         TPM_UNDEFINED,
143         TPM_UNDEFINED,          /* 55 */
144         TPM_UNDEFINED,
145         TPM_UNDEFINED,
146         TPM_UNDEFINED,
147         TPM_UNDEFINED,
148         TPM_MEDIUM,             /* 60 */
149         TPM_MEDIUM,
150         TPM_MEDIUM,
151         TPM_SHORT,
152         TPM_SHORT,
153         TPM_MEDIUM,             /* 65 */
154         TPM_UNDEFINED,
155         TPM_UNDEFINED,
156         TPM_UNDEFINED,
157         TPM_UNDEFINED,
158         TPM_SHORT,              /* 70 */
159         TPM_SHORT,
160         TPM_UNDEFINED,
161         TPM_UNDEFINED,
162         TPM_UNDEFINED,
163         TPM_UNDEFINED,          /* 75 */
164         TPM_UNDEFINED,
165         TPM_UNDEFINED,
166         TPM_UNDEFINED,
167         TPM_UNDEFINED,
168         TPM_LONG,               /* 80 */
169         TPM_UNDEFINED,
170         TPM_MEDIUM,
171         TPM_LONG,
172         TPM_SHORT,
173         TPM_UNDEFINED,          /* 85 */
174         TPM_UNDEFINED,
175         TPM_UNDEFINED,
176         TPM_UNDEFINED,
177         TPM_UNDEFINED,
178         TPM_SHORT,              /* 90 */
179         TPM_SHORT,
180         TPM_SHORT,
181         TPM_SHORT,
182         TPM_SHORT,
183         TPM_UNDEFINED,          /* 95 */
184         TPM_UNDEFINED,
185         TPM_UNDEFINED,
186         TPM_UNDEFINED,
187         TPM_UNDEFINED,
188         TPM_MEDIUM,             /* 100 */
189         TPM_SHORT,
190         TPM_SHORT,
191         TPM_UNDEFINED,
192         TPM_UNDEFINED,
193         TPM_UNDEFINED,          /* 105 */
194         TPM_UNDEFINED,
195         TPM_UNDEFINED,
196         TPM_UNDEFINED,
197         TPM_UNDEFINED,
198         TPM_SHORT,              /* 110 */
199         TPM_SHORT,
200         TPM_SHORT,
201         TPM_SHORT,
202         TPM_SHORT,
203         TPM_SHORT,              /* 115 */
204         TPM_SHORT,
205         TPM_SHORT,
206         TPM_UNDEFINED,
207         TPM_UNDEFINED,
208         TPM_LONG,               /* 120 */
209         TPM_LONG,
210         TPM_MEDIUM,
211         TPM_UNDEFINED,
212         TPM_SHORT,
213         TPM_SHORT,              /* 125 */
214         TPM_SHORT,
215         TPM_LONG,
216         TPM_SHORT,
217         TPM_SHORT,
218         TPM_SHORT,              /* 130 */
219         TPM_MEDIUM,
220         TPM_UNDEFINED,
221         TPM_SHORT,
222         TPM_MEDIUM,
223         TPM_UNDEFINED,          /* 135 */
224         TPM_UNDEFINED,
225         TPM_UNDEFINED,
226         TPM_UNDEFINED,
227         TPM_UNDEFINED,
228         TPM_SHORT,              /* 140 */
229         TPM_SHORT,
230         TPM_UNDEFINED,
231         TPM_UNDEFINED,
232         TPM_UNDEFINED,
233         TPM_UNDEFINED,          /* 145 */
234         TPM_UNDEFINED,
235         TPM_UNDEFINED,
236         TPM_UNDEFINED,
237         TPM_UNDEFINED,
238         TPM_SHORT,              /* 150 */
239         TPM_MEDIUM,
240         TPM_MEDIUM,
241         TPM_SHORT,
242         TPM_SHORT,
243         TPM_UNDEFINED,          /* 155 */
244         TPM_UNDEFINED,
245         TPM_UNDEFINED,
246         TPM_UNDEFINED,
247         TPM_UNDEFINED,
248         TPM_SHORT,              /* 160 */
249         TPM_SHORT,
250         TPM_SHORT,
251         TPM_SHORT,
252         TPM_UNDEFINED,
253         TPM_UNDEFINED,          /* 165 */
254         TPM_UNDEFINED,
255         TPM_UNDEFINED,
256         TPM_UNDEFINED,
257         TPM_UNDEFINED,
258         TPM_LONG,               /* 170 */
259         TPM_UNDEFINED,
260         TPM_UNDEFINED,
261         TPM_UNDEFINED,
262         TPM_UNDEFINED,
263         TPM_UNDEFINED,          /* 175 */
264         TPM_UNDEFINED,
265         TPM_UNDEFINED,
266         TPM_UNDEFINED,
267         TPM_UNDEFINED,
268         TPM_MEDIUM,             /* 180 */
269         TPM_SHORT,
270         TPM_MEDIUM,
271         TPM_MEDIUM,
272         TPM_MEDIUM,
273         TPM_MEDIUM,             /* 185 */
274         TPM_SHORT,
275         TPM_UNDEFINED,
276         TPM_UNDEFINED,
277         TPM_UNDEFINED,
278         TPM_UNDEFINED,          /* 190 */
279         TPM_UNDEFINED,
280         TPM_UNDEFINED,
281         TPM_UNDEFINED,
282         TPM_UNDEFINED,
283         TPM_UNDEFINED,          /* 195 */
284         TPM_UNDEFINED,
285         TPM_UNDEFINED,
286         TPM_UNDEFINED,
287         TPM_UNDEFINED,
288         TPM_SHORT,              /* 200 */
289         TPM_UNDEFINED,
290         TPM_UNDEFINED,
291         TPM_UNDEFINED,
292         TPM_SHORT,
293         TPM_SHORT,              /* 205 */
294         TPM_SHORT,
295         TPM_SHORT,
296         TPM_SHORT,
297         TPM_SHORT,
298         TPM_MEDIUM,             /* 210 */
299         TPM_UNDEFINED,
300         TPM_MEDIUM,
301         TPM_MEDIUM,
302         TPM_MEDIUM,
303         TPM_UNDEFINED,          /* 215 */
304         TPM_MEDIUM,
305         TPM_UNDEFINED,
306         TPM_UNDEFINED,
307         TPM_SHORT,
308         TPM_SHORT,              /* 220 */
309         TPM_SHORT,
310         TPM_SHORT,
311         TPM_SHORT,
312         TPM_SHORT,
313         TPM_UNDEFINED,          /* 225 */
314         TPM_UNDEFINED,
315         TPM_UNDEFINED,
316         TPM_UNDEFINED,
317         TPM_UNDEFINED,
318         TPM_SHORT,              /* 230 */
319         TPM_LONG,
320         TPM_MEDIUM,
321         TPM_UNDEFINED,
322         TPM_UNDEFINED,
323         TPM_UNDEFINED,          /* 235 */
324         TPM_UNDEFINED,
325         TPM_UNDEFINED,
326         TPM_UNDEFINED,
327         TPM_UNDEFINED,
328         TPM_SHORT,              /* 240 */
329         TPM_UNDEFINED,
330         TPM_MEDIUM,
331 };
332
333 static void user_reader_timeout(unsigned long ptr)
334 {
335         struct tpm_chip *chip = (struct tpm_chip *) ptr;
336
337         schedule_work(&chip->work);
338 }
339
340 static void timeout_work(struct work_struct *work)
341 {
342         struct tpm_chip *chip = container_of(work, struct tpm_chip, work);
343
344         mutex_lock(&chip->buffer_mutex);
345         atomic_set(&chip->data_pending, 0);
346         memset(chip->data_buffer, 0, TPM_BUFSIZE);
347         mutex_unlock(&chip->buffer_mutex);
348 }
349
350 /*
351  * Returns max number of jiffies to wait
352  */
353 unsigned long tpm_calc_ordinal_duration(struct tpm_chip *chip,
354                                            u32 ordinal)
355 {
356         int duration_idx = TPM_UNDEFINED;
357         int duration = 0;
358
359         if (ordinal < TPM_MAX_ORDINAL)
360                 duration_idx = tpm_ordinal_duration[ordinal];
361         else if ((ordinal & TPM_PROTECTED_ORDINAL_MASK) <
362                  TPM_MAX_PROTECTED_ORDINAL)
363                 duration_idx =
364                     tpm_protected_ordinal_duration[ordinal &
365                                                    TPM_PROTECTED_ORDINAL_MASK];
366
367         if (duration_idx != TPM_UNDEFINED)
368                 duration = chip->vendor.duration[duration_idx];
369         if (duration <= 0)
370                 return 2 * 60 * HZ;
371         else
372                 return duration;
373 }
374 EXPORT_SYMBOL_GPL(tpm_calc_ordinal_duration);
375
376 /*
377  * Internal kernel interface to transmit TPM commands
378  */
379 static ssize_t tpm_transmit(struct tpm_chip *chip, const char *buf,
380                             size_t bufsiz)
381 {
382         ssize_t rc;
383         u32 count, ordinal;
384         unsigned long stop;
385
386         count = be32_to_cpu(*((__be32 *) (buf + 2)));
387         ordinal = be32_to_cpu(*((__be32 *) (buf + 6)));
388         if (count == 0)
389                 return -ENODATA;
390         if (count > bufsiz) {
391                 dev_err(chip->dev,
392                         "invalid count value %x %zx \n", count, bufsiz);
393                 return -E2BIG;
394         }
395
396         mutex_lock(&chip->tpm_mutex);
397
398         if ((rc = chip->vendor.send(chip, (u8 *) buf, count)) < 0) {
399                 dev_err(chip->dev,
400                         "tpm_transmit: tpm_send: error %zd\n", rc);
401                 goto out;
402         }
403
404         if (chip->vendor.irq)
405                 goto out_recv;
406
407         stop = jiffies + tpm_calc_ordinal_duration(chip, ordinal);
408         do {
409                 u8 status = chip->vendor.status(chip);
410                 if ((status & chip->vendor.req_complete_mask) ==
411                     chip->vendor.req_complete_val)
412                         goto out_recv;
413
414                 if ((status == chip->vendor.req_canceled)) {
415                         dev_err(chip->dev, "Operation Canceled\n");
416                         rc = -ECANCELED;
417                         goto out;
418                 }
419
420                 msleep(TPM_TIMEOUT);    /* CHECK */
421                 rmb();
422         } while (time_before(jiffies, stop));
423
424         chip->vendor.cancel(chip);
425         dev_err(chip->dev, "Operation Timed out\n");
426         rc = -ETIME;
427         goto out;
428
429 out_recv:
430         rc = chip->vendor.recv(chip, (u8 *) buf, bufsiz);
431         if (rc < 0)
432                 dev_err(chip->dev,
433                         "tpm_transmit: tpm_recv: error %zd\n", rc);
434 out:
435         mutex_unlock(&chip->tpm_mutex);
436         return rc;
437 }
438
439 #define TPM_DIGEST_SIZE 20
440 #define TPM_ERROR_SIZE 10
441 #define TPM_RET_CODE_IDX 6
442
443 enum tpm_capabilities {
444         TPM_CAP_FLAG = cpu_to_be32(4),
445         TPM_CAP_PROP = cpu_to_be32(5),
446         CAP_VERSION_1_1 = cpu_to_be32(0x06),
447         CAP_VERSION_1_2 = cpu_to_be32(0x1A)
448 };
449
450 enum tpm_sub_capabilities {
451         TPM_CAP_PROP_PCR = cpu_to_be32(0x101),
452         TPM_CAP_PROP_MANUFACTURER = cpu_to_be32(0x103),
453         TPM_CAP_FLAG_PERM = cpu_to_be32(0x108),
454         TPM_CAP_FLAG_VOL = cpu_to_be32(0x109),
455         TPM_CAP_PROP_OWNER = cpu_to_be32(0x111),
456         TPM_CAP_PROP_TIS_TIMEOUT = cpu_to_be32(0x115),
457         TPM_CAP_PROP_TIS_DURATION = cpu_to_be32(0x120),
458
459 };
460
461 static ssize_t transmit_cmd(struct tpm_chip *chip, struct tpm_cmd_t *cmd,
462                             int len, const char *desc)
463 {
464         int err;
465
466         len = tpm_transmit(chip,(u8 *) cmd, len);
467         if (len <  0)
468                 return len;
469         if (len == TPM_ERROR_SIZE) {
470                 err = be32_to_cpu(cmd->header.out.return_code);
471                 dev_dbg(chip->dev, "A TPM error (%d) occurred %s\n", err, desc);
472                 return err;
473         }
474         return 0;
475 }
476
477 #define TPM_INTERNAL_RESULT_SIZE 200
478 #define TPM_TAG_RQU_COMMAND cpu_to_be16(193)
479 #define TPM_ORD_GET_CAP cpu_to_be32(101)
480
481 static const struct tpm_input_header tpm_getcap_header = {
482         .tag = TPM_TAG_RQU_COMMAND,
483         .length = cpu_to_be32(22),
484         .ordinal = TPM_ORD_GET_CAP
485 };
486
487 ssize_t tpm_getcap(struct device *dev, __be32 subcap_id, cap_t *cap,
488                    const char *desc)
489 {
490         struct tpm_cmd_t tpm_cmd;
491         int rc;
492         struct tpm_chip *chip = dev_get_drvdata(dev);
493
494         tpm_cmd.header.in = tpm_getcap_header;
495         if (subcap_id == CAP_VERSION_1_1 || subcap_id == CAP_VERSION_1_2) {
496                 tpm_cmd.params.getcap_in.cap = subcap_id;
497                 /*subcap field not necessary */
498                 tpm_cmd.params.getcap_in.subcap_size = cpu_to_be32(0);
499                 tpm_cmd.header.in.length -= cpu_to_be32(sizeof(__be32));
500         } else {
501                 if (subcap_id == TPM_CAP_FLAG_PERM ||
502                     subcap_id == TPM_CAP_FLAG_VOL)
503                         tpm_cmd.params.getcap_in.cap = TPM_CAP_FLAG;
504                 else
505                         tpm_cmd.params.getcap_in.cap = TPM_CAP_PROP;
506                 tpm_cmd.params.getcap_in.subcap_size = cpu_to_be32(4);
507                 tpm_cmd.params.getcap_in.subcap = subcap_id;
508         }
509         rc = transmit_cmd(chip, &tpm_cmd, TPM_INTERNAL_RESULT_SIZE, desc);
510         if (!rc)
511                 *cap = tpm_cmd.params.getcap_out.cap;
512         return rc;
513 }
514
515 void tpm_gen_interrupt(struct tpm_chip *chip)
516 {
517         struct  tpm_cmd_t tpm_cmd;
518         ssize_t rc;
519
520         tpm_cmd.header.in = tpm_getcap_header;
521         tpm_cmd.params.getcap_in.cap = TPM_CAP_PROP;
522         tpm_cmd.params.getcap_in.subcap_size = cpu_to_be32(4);
523         tpm_cmd.params.getcap_in.subcap = TPM_CAP_PROP_TIS_TIMEOUT;
524
525         rc = transmit_cmd(chip, &tpm_cmd, TPM_INTERNAL_RESULT_SIZE,
526                         "attempting to determine the timeouts");
527 }
528 EXPORT_SYMBOL_GPL(tpm_gen_interrupt);
529
530 void tpm_get_timeouts(struct tpm_chip *chip)
531 {
532         struct tpm_cmd_t tpm_cmd;
533         struct timeout_t *timeout_cap;
534         struct duration_t *duration_cap;
535         ssize_t rc;
536         u32 timeout;
537
538         tpm_cmd.header.in = tpm_getcap_header;
539         tpm_cmd.params.getcap_in.cap = TPM_CAP_PROP;
540         tpm_cmd.params.getcap_in.subcap_size = cpu_to_be32(4);
541         tpm_cmd.params.getcap_in.subcap = TPM_CAP_PROP_TIS_TIMEOUT;
542
543         rc = transmit_cmd(chip, &tpm_cmd, TPM_INTERNAL_RESULT_SIZE,
544                         "attempting to determine the timeouts");
545         if (rc)
546                 goto duration;
547
548         if (be32_to_cpu(tpm_cmd.header.out.length)
549             != 4 * sizeof(u32))
550                 goto duration;
551
552         timeout_cap = &tpm_cmd.params.getcap_out.cap.timeout;
553         /* Don't overwrite default if value is 0 */
554         timeout = be32_to_cpu(timeout_cap->a);
555         if (timeout)
556                 chip->vendor.timeout_a = usecs_to_jiffies(timeout);
557         timeout = be32_to_cpu(timeout_cap->b);
558         if (timeout)
559                 chip->vendor.timeout_b = usecs_to_jiffies(timeout);
560         timeout = be32_to_cpu(timeout_cap->c);
561         if (timeout)
562                 chip->vendor.timeout_c = usecs_to_jiffies(timeout);
563         timeout = be32_to_cpu(timeout_cap->d);
564         if (timeout)
565                 chip->vendor.timeout_d = usecs_to_jiffies(timeout);
566
567 duration:
568         tpm_cmd.header.in = tpm_getcap_header;
569         tpm_cmd.params.getcap_in.cap = TPM_CAP_PROP;
570         tpm_cmd.params.getcap_in.subcap_size = cpu_to_be32(4);
571         tpm_cmd.params.getcap_in.subcap = TPM_CAP_PROP_TIS_DURATION;
572
573         rc = transmit_cmd(chip, &tpm_cmd, TPM_INTERNAL_RESULT_SIZE,
574                         "attempting to determine the durations");
575         if (rc)
576                 return;
577
578         if (be32_to_cpu(tpm_cmd.header.out.return_code) != 0 ||
579             be32_to_cpu(tpm_cmd.header.out.length)
580             != sizeof(tpm_cmd.header.out) + sizeof(u32) + 3 * sizeof(u32))
581                 return;
582
583         duration_cap = &tpm_cmd.params.getcap_out.cap.duration;
584         chip->vendor.duration[TPM_SHORT] =
585             usecs_to_jiffies(be32_to_cpu(duration_cap->tpm_short));
586         chip->vendor.duration[TPM_MEDIUM] =
587             usecs_to_jiffies(be32_to_cpu(duration_cap->tpm_medium));
588         chip->vendor.duration[TPM_LONG] =
589             usecs_to_jiffies(be32_to_cpu(duration_cap->tpm_long));
590
591         /* The Broadcom BCM0102 chipset in a Dell Latitude D820 gets the above
592          * value wrong and apparently reports msecs rather than usecs. So we
593          * fix up the resulting too-small TPM_SHORT value to make things work.
594          * We also scale the TPM_MEDIUM and -_LONG values by 1000.
595          */
596         if (chip->vendor.duration[TPM_SHORT] < (HZ / 100)) {
597                 chip->vendor.duration[TPM_SHORT] = HZ;
598                 chip->vendor.duration[TPM_MEDIUM] *= 1000;
599                 chip->vendor.duration[TPM_LONG] *= 1000;
600                 dev_info(chip->dev, "Adjusting TPM timeout parameters.");
601         }
602 }
603 EXPORT_SYMBOL_GPL(tpm_get_timeouts);
604
605 void tpm_continue_selftest(struct tpm_chip *chip)
606 {
607         u8 data[] = {
608                 0, 193,                 /* TPM_TAG_RQU_COMMAND */
609                 0, 0, 0, 10,            /* length */
610                 0, 0, 0, 83,            /* TPM_ORD_GetCapability */
611         };
612
613         tpm_transmit(chip, data, sizeof(data));
614 }
615 EXPORT_SYMBOL_GPL(tpm_continue_selftest);
616
617 ssize_t tpm_show_enabled(struct device * dev, struct device_attribute * attr,
618                         char *buf)
619 {
620         cap_t cap;
621         ssize_t rc;
622
623         rc = tpm_getcap(dev, TPM_CAP_FLAG_PERM, &cap,
624                          "attempting to determine the permanent enabled state");
625         if (rc)
626                 return 0;
627
628         rc = sprintf(buf, "%d\n", !cap.perm_flags.disable);
629         return rc;
630 }
631 EXPORT_SYMBOL_GPL(tpm_show_enabled);
632
633 ssize_t tpm_show_active(struct device * dev, struct device_attribute * attr,
634                         char *buf)
635 {
636         cap_t cap;
637         ssize_t rc;
638
639         rc = tpm_getcap(dev, TPM_CAP_FLAG_PERM, &cap,
640                          "attempting to determine the permanent active state");
641         if (rc)
642                 return 0;
643
644         rc = sprintf(buf, "%d\n", !cap.perm_flags.deactivated);
645         return rc;
646 }
647 EXPORT_SYMBOL_GPL(tpm_show_active);
648
649 ssize_t tpm_show_owned(struct device * dev, struct device_attribute * attr,
650                         char *buf)
651 {
652         cap_t cap;
653         ssize_t rc;
654
655         rc = tpm_getcap(dev, TPM_CAP_PROP_OWNER, &cap,
656                          "attempting to determine the owner state");
657         if (rc)
658                 return 0;
659
660         rc = sprintf(buf, "%d\n", cap.owned);
661         return rc;
662 }
663 EXPORT_SYMBOL_GPL(tpm_show_owned);
664
665 ssize_t tpm_show_temp_deactivated(struct device * dev,
666                                 struct device_attribute * attr, char *buf)
667 {
668         cap_t cap;
669         ssize_t rc;
670
671         rc = tpm_getcap(dev, TPM_CAP_FLAG_VOL, &cap,
672                          "attempting to determine the temporary state");
673         if (rc)
674                 return 0;
675
676         rc = sprintf(buf, "%d\n", cap.stclear_flags.deactivated);
677         return rc;
678 }
679 EXPORT_SYMBOL_GPL(tpm_show_temp_deactivated);
680
681 /*
682  * tpm_chip_find_get - return tpm_chip for given chip number
683  */
684 static struct tpm_chip *tpm_chip_find_get(int chip_num)
685 {
686         struct tpm_chip *pos, *chip = NULL;
687
688         rcu_read_lock();
689         list_for_each_entry_rcu(pos, &tpm_chip_list, list) {
690                 if (chip_num != TPM_ANY_NUM && chip_num != pos->dev_num)
691                         continue;
692
693                 if (try_module_get(pos->dev->driver->owner)) {
694                         chip = pos;
695                         break;
696                 }
697         }
698         rcu_read_unlock();
699         return chip;
700 }
701
702 #define TPM_ORDINAL_PCRREAD cpu_to_be32(21)
703 #define READ_PCR_RESULT_SIZE 30
704 static struct tpm_input_header pcrread_header = {
705         .tag = TPM_TAG_RQU_COMMAND,
706         .length = cpu_to_be32(14),
707         .ordinal = TPM_ORDINAL_PCRREAD
708 };
709
710 int __tpm_pcr_read(struct tpm_chip *chip, int pcr_idx, u8 *res_buf)
711 {
712         int rc;
713         struct tpm_cmd_t cmd;
714
715         cmd.header.in = pcrread_header;
716         cmd.params.pcrread_in.pcr_idx = cpu_to_be32(pcr_idx);
717         rc = transmit_cmd(chip, &cmd, READ_PCR_RESULT_SIZE,
718                           "attempting to read a pcr value");
719
720         if (rc == 0)
721                 memcpy(res_buf, cmd.params.pcrread_out.pcr_result,
722                        TPM_DIGEST_SIZE);
723         return rc;
724 }
725
726 /**
727  * tpm_pcr_read - read a pcr value
728  * @chip_num:   tpm idx # or ANY
729  * @pcr_idx:    pcr idx to retrieve
730  * @res_buf:    TPM_PCR value
731  *              size of res_buf is 20 bytes (or NULL if you don't care)
732  *
733  * The TPM driver should be built-in, but for whatever reason it
734  * isn't, protect against the chip disappearing, by incrementing
735  * the module usage count.
736  */
737 int tpm_pcr_read(u32 chip_num, int pcr_idx, u8 *res_buf)
738 {
739         struct tpm_chip *chip;
740         int rc;
741
742         chip = tpm_chip_find_get(chip_num);
743         if (chip == NULL)
744                 return -ENODEV;
745         rc = __tpm_pcr_read(chip, pcr_idx, res_buf);
746         tpm_chip_put(chip);
747         return rc;
748 }
749 EXPORT_SYMBOL_GPL(tpm_pcr_read);
750
751 /**
752  * tpm_pcr_extend - extend pcr value with hash
753  * @chip_num:   tpm idx # or AN&
754  * @pcr_idx:    pcr idx to extend
755  * @hash:       hash value used to extend pcr value
756  *
757  * The TPM driver should be built-in, but for whatever reason it
758  * isn't, protect against the chip disappearing, by incrementing
759  * the module usage count.
760  */
761 #define TPM_ORD_PCR_EXTEND cpu_to_be32(20)
762 #define EXTEND_PCR_RESULT_SIZE 34
763 static struct tpm_input_header pcrextend_header = {
764         .tag = TPM_TAG_RQU_COMMAND,
765         .length = cpu_to_be32(34),
766         .ordinal = TPM_ORD_PCR_EXTEND
767 };
768
769 int tpm_pcr_extend(u32 chip_num, int pcr_idx, const u8 *hash)
770 {
771         struct tpm_cmd_t cmd;
772         int rc;
773         struct tpm_chip *chip;
774
775         chip = tpm_chip_find_get(chip_num);
776         if (chip == NULL)
777                 return -ENODEV;
778
779         cmd.header.in = pcrextend_header;
780         cmd.params.pcrextend_in.pcr_idx = cpu_to_be32(pcr_idx);
781         memcpy(cmd.params.pcrextend_in.hash, hash, TPM_DIGEST_SIZE);
782         rc = transmit_cmd(chip, &cmd, EXTEND_PCR_RESULT_SIZE,
783                           "attempting extend a PCR value");
784
785         tpm_chip_put(chip);
786         return rc;
787 }
788 EXPORT_SYMBOL_GPL(tpm_pcr_extend);
789
790 int tpm_send(u32 chip_num, void *cmd, size_t buflen)
791 {
792         struct tpm_chip *chip;
793         int rc;
794
795         chip = tpm_chip_find_get(chip_num);
796         if (chip == NULL)
797                 return -ENODEV;
798
799         rc = transmit_cmd(chip, cmd, buflen, "attempting tpm_cmd");
800
801         tpm_chip_put(chip);
802         return rc;
803 }
804 EXPORT_SYMBOL_GPL(tpm_send);
805
806 ssize_t tpm_show_pcrs(struct device *dev, struct device_attribute *attr,
807                       char *buf)
808 {
809         cap_t cap;
810         u8 digest[TPM_DIGEST_SIZE];
811         ssize_t rc;
812         int i, j, num_pcrs;
813         char *str = buf;
814         struct tpm_chip *chip = dev_get_drvdata(dev);
815
816         rc = tpm_getcap(dev, TPM_CAP_PROP_PCR, &cap,
817                         "attempting to determine the number of PCRS");
818         if (rc)
819                 return 0;
820
821         num_pcrs = be32_to_cpu(cap.num_pcrs);
822         for (i = 0; i < num_pcrs; i++) {
823                 rc = __tpm_pcr_read(chip, i, digest);
824                 if (rc)
825                         break;
826                 str += sprintf(str, "PCR-%02d: ", i);
827                 for (j = 0; j < TPM_DIGEST_SIZE; j++)
828                         str += sprintf(str, "%02X ", digest[j]);
829                 str += sprintf(str, "\n");
830         }
831         return str - buf;
832 }
833 EXPORT_SYMBOL_GPL(tpm_show_pcrs);
834
835 #define  READ_PUBEK_RESULT_SIZE 314
836 #define TPM_ORD_READPUBEK cpu_to_be32(124)
837 struct tpm_input_header tpm_readpubek_header = {
838         .tag = TPM_TAG_RQU_COMMAND,
839         .length = cpu_to_be32(30),
840         .ordinal = TPM_ORD_READPUBEK
841 };
842
843 ssize_t tpm_show_pubek(struct device *dev, struct device_attribute *attr,
844                        char *buf)
845 {
846         u8 *data;
847         struct tpm_cmd_t tpm_cmd;
848         ssize_t err;
849         int i, rc;
850         char *str = buf;
851
852         struct tpm_chip *chip = dev_get_drvdata(dev);
853
854         tpm_cmd.header.in = tpm_readpubek_header;
855         err = transmit_cmd(chip, &tpm_cmd, READ_PUBEK_RESULT_SIZE,
856                         "attempting to read the PUBEK");
857         if (err)
858                 goto out;
859
860         /* 
861            ignore header 10 bytes
862            algorithm 32 bits (1 == RSA )
863            encscheme 16 bits
864            sigscheme 16 bits
865            parameters (RSA 12->bytes: keybit, #primes, expbit)  
866            keylenbytes 32 bits
867            256 byte modulus
868            ignore checksum 20 bytes
869          */
870         data = tpm_cmd.params.readpubek_out_buffer;
871         str +=
872             sprintf(str,
873                     "Algorithm: %02X %02X %02X %02X\nEncscheme: %02X %02X\n"
874                     "Sigscheme: %02X %02X\nParameters: %02X %02X %02X %02X"
875                     " %02X %02X %02X %02X %02X %02X %02X %02X\n"
876                     "Modulus length: %d\nModulus: \n",
877                     data[10], data[11], data[12], data[13], data[14],
878                     data[15], data[16], data[17], data[22], data[23],
879                     data[24], data[25], data[26], data[27], data[28],
880                     data[29], data[30], data[31], data[32], data[33],
881                     be32_to_cpu(*((__be32 *) (data + 34))));
882
883         for (i = 0; i < 256; i++) {
884                 str += sprintf(str, "%02X ", data[i + 38]);
885                 if ((i + 1) % 16 == 0)
886                         str += sprintf(str, "\n");
887         }
888 out:
889         rc = str - buf;
890         return rc;
891 }
892 EXPORT_SYMBOL_GPL(tpm_show_pubek);
893
894
895 ssize_t tpm_show_caps(struct device *dev, struct device_attribute *attr,
896                       char *buf)
897 {
898         cap_t cap;
899         ssize_t rc;
900         char *str = buf;
901
902         rc = tpm_getcap(dev, TPM_CAP_PROP_MANUFACTURER, &cap,
903                         "attempting to determine the manufacturer");
904         if (rc)
905                 return 0;
906         str += sprintf(str, "Manufacturer: 0x%x\n",
907                        be32_to_cpu(cap.manufacturer_id));
908
909         rc = tpm_getcap(dev, CAP_VERSION_1_1, &cap,
910                         "attempting to determine the 1.1 version");
911         if (rc)
912                 return 0;
913         str += sprintf(str,
914                        "TCG version: %d.%d\nFirmware version: %d.%d\n",
915                        cap.tpm_version.Major, cap.tpm_version.Minor,
916                        cap.tpm_version.revMajor, cap.tpm_version.revMinor);
917         return str - buf;
918 }
919 EXPORT_SYMBOL_GPL(tpm_show_caps);
920
921 ssize_t tpm_show_caps_1_2(struct device * dev,
922                           struct device_attribute * attr, char *buf)
923 {
924         cap_t cap;
925         ssize_t rc;
926         char *str = buf;
927
928         rc = tpm_getcap(dev, TPM_CAP_PROP_MANUFACTURER, &cap,
929                         "attempting to determine the manufacturer");
930         if (rc)
931                 return 0;
932         str += sprintf(str, "Manufacturer: 0x%x\n",
933                        be32_to_cpu(cap.manufacturer_id));
934         rc = tpm_getcap(dev, CAP_VERSION_1_2, &cap,
935                          "attempting to determine the 1.2 version");
936         if (rc)
937                 return 0;
938         str += sprintf(str,
939                        "TCG version: %d.%d\nFirmware version: %d.%d\n",
940                        cap.tpm_version_1_2.Major, cap.tpm_version_1_2.Minor,
941                        cap.tpm_version_1_2.revMajor,
942                        cap.tpm_version_1_2.revMinor);
943         return str - buf;
944 }
945 EXPORT_SYMBOL_GPL(tpm_show_caps_1_2);
946
947 ssize_t tpm_store_cancel(struct device *dev, struct device_attribute *attr,
948                         const char *buf, size_t count)
949 {
950         struct tpm_chip *chip = dev_get_drvdata(dev);
951         if (chip == NULL)
952                 return 0;
953
954         chip->vendor.cancel(chip);
955         return count;
956 }
957 EXPORT_SYMBOL_GPL(tpm_store_cancel);
958
959 /*
960  * Device file system interface to the TPM
961  *
962  * It's assured that the chip will be opened just once,
963  * by the check of is_open variable, which is protected
964  * by driver_lock.
965  */
966 int tpm_open(struct inode *inode, struct file *file)
967 {
968         int minor = iminor(inode);
969         struct tpm_chip *chip = NULL, *pos;
970
971         rcu_read_lock();
972         list_for_each_entry_rcu(pos, &tpm_chip_list, list) {
973                 if (pos->vendor.miscdev.minor == minor) {
974                         chip = pos;
975                         get_device(chip->dev);
976                         break;
977                 }
978         }
979         rcu_read_unlock();
980
981         if (!chip)
982                 return -ENODEV;
983
984         if (test_and_set_bit(0, &chip->is_open)) {
985                 dev_dbg(chip->dev, "Another process owns this TPM\n");
986                 put_device(chip->dev);
987                 return -EBUSY;
988         }
989
990         chip->data_buffer = kzalloc(TPM_BUFSIZE, GFP_KERNEL);
991         if (chip->data_buffer == NULL) {
992                 clear_bit(0, &chip->is_open);
993                 put_device(chip->dev);
994                 return -ENOMEM;
995         }
996
997         atomic_set(&chip->data_pending, 0);
998
999         file->private_data = chip;
1000         return 0;
1001 }
1002 EXPORT_SYMBOL_GPL(tpm_open);
1003
1004 /*
1005  * Called on file close
1006  */
1007 int tpm_release(struct inode *inode, struct file *file)
1008 {
1009         struct tpm_chip *chip = file->private_data;
1010
1011         del_singleshot_timer_sync(&chip->user_read_timer);
1012         flush_work_sync(&chip->work);
1013         file->private_data = NULL;
1014         atomic_set(&chip->data_pending, 0);
1015         kfree(chip->data_buffer);
1016         clear_bit(0, &chip->is_open);
1017         put_device(chip->dev);
1018         return 0;
1019 }
1020 EXPORT_SYMBOL_GPL(tpm_release);
1021
1022 ssize_t tpm_write(struct file *file, const char __user *buf,
1023                   size_t size, loff_t *off)
1024 {
1025         struct tpm_chip *chip = file->private_data;
1026         size_t in_size = size, out_size;
1027
1028         /* cannot perform a write until the read has cleared
1029            either via tpm_read or a user_read_timer timeout */
1030         while (atomic_read(&chip->data_pending) != 0)
1031                 msleep(TPM_TIMEOUT);
1032
1033         mutex_lock(&chip->buffer_mutex);
1034
1035         if (in_size > TPM_BUFSIZE)
1036                 in_size = TPM_BUFSIZE;
1037
1038         if (copy_from_user
1039             (chip->data_buffer, (void __user *) buf, in_size)) {
1040                 mutex_unlock(&chip->buffer_mutex);
1041                 return -EFAULT;
1042         }
1043
1044         /* atomic tpm command send and result receive */
1045         out_size = tpm_transmit(chip, chip->data_buffer, TPM_BUFSIZE);
1046
1047         atomic_set(&chip->data_pending, out_size);
1048         mutex_unlock(&chip->buffer_mutex);
1049
1050         /* Set a timeout by which the reader must come claim the result */
1051         mod_timer(&chip->user_read_timer, jiffies + (60 * HZ));
1052
1053         return in_size;
1054 }
1055 EXPORT_SYMBOL_GPL(tpm_write);
1056
1057 ssize_t tpm_read(struct file *file, char __user *buf,
1058                  size_t size, loff_t *off)
1059 {
1060         struct tpm_chip *chip = file->private_data;
1061         ssize_t ret_size;
1062
1063         del_singleshot_timer_sync(&chip->user_read_timer);
1064         flush_work_sync(&chip->work);
1065         ret_size = atomic_read(&chip->data_pending);
1066         atomic_set(&chip->data_pending, 0);
1067         if (ret_size > 0) {     /* relay data */
1068                 if (size < ret_size)
1069                         ret_size = size;
1070
1071                 mutex_lock(&chip->buffer_mutex);
1072                 if (copy_to_user(buf, chip->data_buffer, ret_size))
1073                         ret_size = -EFAULT;
1074                 mutex_unlock(&chip->buffer_mutex);
1075         }
1076
1077         return ret_size;
1078 }
1079 EXPORT_SYMBOL_GPL(tpm_read);
1080
1081 void tpm_remove_hardware(struct device *dev)
1082 {
1083         struct tpm_chip *chip = dev_get_drvdata(dev);
1084
1085         if (chip == NULL) {
1086                 dev_err(dev, "No device data found\n");
1087                 return;
1088         }
1089
1090         spin_lock(&driver_lock);
1091         list_del_rcu(&chip->list);
1092         spin_unlock(&driver_lock);
1093         synchronize_rcu();
1094
1095         misc_deregister(&chip->vendor.miscdev);
1096         sysfs_remove_group(&dev->kobj, chip->vendor.attr_group);
1097         tpm_bios_log_teardown(chip->bios_dir);
1098
1099         /* write it this way to be explicit (chip->dev == dev) */
1100         put_device(chip->dev);
1101 }
1102 EXPORT_SYMBOL_GPL(tpm_remove_hardware);
1103
1104 #define TPM_ORD_SAVESTATE cpu_to_be32(152)
1105 #define SAVESTATE_RESULT_SIZE 10
1106
1107 static struct tpm_input_header savestate_header = {
1108         .tag = TPM_TAG_RQU_COMMAND,
1109         .length = cpu_to_be32(10),
1110         .ordinal = TPM_ORD_SAVESTATE
1111 };
1112
1113 /*
1114  * We are about to suspend. Save the TPM state
1115  * so that it can be restored.
1116  */
1117 int tpm_pm_suspend(struct device *dev, pm_message_t pm_state)
1118 {
1119         struct tpm_chip *chip = dev_get_drvdata(dev);
1120         struct tpm_cmd_t cmd;
1121         int rc;
1122
1123         u8 dummy_hash[TPM_DIGEST_SIZE] = { 0 };
1124
1125         if (chip == NULL)
1126                 return -ENODEV;
1127
1128         /* for buggy tpm, flush pcrs with extend to selected dummy */
1129         if (tpm_suspend_pcr) {
1130                 cmd.header.in = pcrextend_header;
1131                 cmd.params.pcrextend_in.pcr_idx = cpu_to_be32(tpm_suspend_pcr);
1132                 memcpy(cmd.params.pcrextend_in.hash, dummy_hash,
1133                        TPM_DIGEST_SIZE);
1134                 rc = transmit_cmd(chip, &cmd, EXTEND_PCR_RESULT_SIZE,
1135                                   "extending dummy pcr before suspend");
1136         }
1137
1138         /* now do the actual savestate */
1139         cmd.header.in = savestate_header;
1140         rc = transmit_cmd(chip, &cmd, SAVESTATE_RESULT_SIZE,
1141                           "sending savestate before suspend");
1142         return rc;
1143 }
1144 EXPORT_SYMBOL_GPL(tpm_pm_suspend);
1145
1146 /*
1147  * Resume from a power safe. The BIOS already restored
1148  * the TPM state.
1149  */
1150 int tpm_pm_resume(struct device *dev)
1151 {
1152         struct tpm_chip *chip = dev_get_drvdata(dev);
1153
1154         if (chip == NULL)
1155                 return -ENODEV;
1156
1157         return 0;
1158 }
1159 EXPORT_SYMBOL_GPL(tpm_pm_resume);
1160
1161 /* In case vendor provided release function, call it too.*/
1162
1163 void tpm_dev_vendor_release(struct tpm_chip *chip)
1164 {
1165         if (chip->vendor.release)
1166                 chip->vendor.release(chip->dev);
1167
1168         clear_bit(chip->dev_num, dev_mask);
1169         kfree(chip->vendor.miscdev.name);
1170 }
1171 EXPORT_SYMBOL_GPL(tpm_dev_vendor_release);
1172
1173
1174 /*
1175  * Once all references to platform device are down to 0,
1176  * release all allocated structures.
1177  */
1178 void tpm_dev_release(struct device *dev)
1179 {
1180         struct tpm_chip *chip = dev_get_drvdata(dev);
1181
1182         tpm_dev_vendor_release(chip);
1183
1184         chip->release(dev);
1185         kfree(chip);
1186 }
1187 EXPORT_SYMBOL_GPL(tpm_dev_release);
1188
1189 /*
1190  * Called from tpm_<specific>.c probe function only for devices 
1191  * the driver has determined it should claim.  Prior to calling
1192  * this function the specific probe function has called pci_enable_device
1193  * upon errant exit from this function specific probe function should call
1194  * pci_disable_device
1195  */
1196 struct tpm_chip *tpm_register_hardware(struct device *dev,
1197                                         const struct tpm_vendor_specific *entry)
1198 {
1199 #define DEVNAME_SIZE 7
1200
1201         char *devname;
1202         struct tpm_chip *chip;
1203
1204         /* Driver specific per-device data */
1205         chip = kzalloc(sizeof(*chip), GFP_KERNEL);
1206         devname = kmalloc(DEVNAME_SIZE, GFP_KERNEL);
1207
1208         if (chip == NULL || devname == NULL)
1209                 goto out_free;
1210
1211         mutex_init(&chip->buffer_mutex);
1212         mutex_init(&chip->tpm_mutex);
1213         INIT_LIST_HEAD(&chip->list);
1214
1215         INIT_WORK(&chip->work, timeout_work);
1216
1217         setup_timer(&chip->user_read_timer, user_reader_timeout,
1218                         (unsigned long)chip);
1219
1220         memcpy(&chip->vendor, entry, sizeof(struct tpm_vendor_specific));
1221
1222         chip->dev_num = find_first_zero_bit(dev_mask, TPM_NUM_DEVICES);
1223
1224         if (chip->dev_num >= TPM_NUM_DEVICES) {
1225                 dev_err(dev, "No available tpm device numbers\n");
1226                 goto out_free;
1227         } else if (chip->dev_num == 0)
1228                 chip->vendor.miscdev.minor = TPM_MINOR;
1229         else
1230                 chip->vendor.miscdev.minor = MISC_DYNAMIC_MINOR;
1231
1232         set_bit(chip->dev_num, dev_mask);
1233
1234         scnprintf(devname, DEVNAME_SIZE, "%s%d", "tpm", chip->dev_num);
1235         chip->vendor.miscdev.name = devname;
1236
1237         chip->vendor.miscdev.parent = dev;
1238         chip->dev = get_device(dev);
1239         chip->release = dev->release;
1240         dev->release = tpm_dev_release;
1241         dev_set_drvdata(dev, chip);
1242
1243         if (misc_register(&chip->vendor.miscdev)) {
1244                 dev_err(chip->dev,
1245                         "unable to misc_register %s, minor %d\n",
1246                         chip->vendor.miscdev.name,
1247                         chip->vendor.miscdev.minor);
1248                 put_device(chip->dev);
1249                 return NULL;
1250         }
1251
1252         if (sysfs_create_group(&dev->kobj, chip->vendor.attr_group)) {
1253                 misc_deregister(&chip->vendor.miscdev);
1254                 put_device(chip->dev);
1255
1256                 return NULL;
1257         }
1258
1259         chip->bios_dir = tpm_bios_log_setup(devname);
1260
1261         /* Make chip available */
1262         spin_lock(&driver_lock);
1263         list_add_rcu(&chip->list, &tpm_chip_list);
1264         spin_unlock(&driver_lock);
1265
1266         return chip;
1267
1268 out_free:
1269         kfree(chip);
1270         kfree(devname);
1271         return NULL;
1272 }
1273 EXPORT_SYMBOL_GPL(tpm_register_hardware);
1274
1275 MODULE_AUTHOR("Leendert van Doorn (leendert@watson.ibm.com)");
1276 MODULE_DESCRIPTION("TPM Driver");
1277 MODULE_VERSION("2.0");
1278 MODULE_LICENSE("GPL");