1/*-
2 * Copyright (c) 2002 Poul-Henning Kamp
3 * Copyright (c) 2002 Networks Associates Technology, Inc.
4 * All rights reserved.
5 *
6 * This software was developed for the FreeBSD Project by Poul-Henning Kamp
7 * and NAI Labs, the Security Research Division of Network Associates, Inc.
8 * under DARPA/SPAWAR contract N66001-01-C-8035 ("CBOSS"), as part of the
9 * DARPA CHATS research program.
10 *
11 * Redistribution and use in source and binary forms, with or without
12 * modification, are permitted provided that the following conditions
13 * are met:
14 * 1. Redistributions of source code must retain the above copyright
15 * notice, this list of conditions and the following disclaimer.
16 * 2. Redistributions in binary form must reproduce the above copyright
17 * notice, this list of conditions and the following disclaimer in the
18 * documentation and/or other materials provided with the distribution.
19 * 3. The names of the authors may not be used to endorse or promote
20 * products derived from this software without specific prior written
21 * permission.
22 *
23 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
24 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
25 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
26 * ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
27 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
28 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
29 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
30 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
31 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
32 * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
33 * SUCH DAMAGE.
34 */
35
36#include <sys/cdefs.h>
37__FBSDID("$FreeBSD: head/sys/geom/geom_disk.c 237648 2012-06-27 16:05:09Z ken $");
38
39#include "opt_geom.h"
40
41#include <sys/param.h>
42#include <sys/systm.h>
43#include <sys/kernel.h>
44#include <sys/sysctl.h>
45#include <sys/bio.h>
46#include <sys/ctype.h>
47#include <sys/fcntl.h>
48#include <sys/malloc.h>
49#include <sys/sbuf.h>
50#include <sys/sysctl.h>
51#include <sys/devicestat.h>
52#include <machine/md_var.h>
53
54#include <sys/lock.h>
55#include <sys/mutex.h>
56#include <geom/geom.h>
57#include <geom/geom_disk.h>
58#include <geom/geom_int.h>
59
60#include <dev/led/led.h>
61
62struct g_disk_softc {
63 struct disk *dp;
64 struct sysctl_ctx_list sysctl_ctx;
65 struct sysctl_oid *sysctl_tree;
66 char led[64];
67 uint32_t state;
68};
69
70static struct mtx g_disk_done_mtx;
71
72static g_access_t g_disk_access;
73static g_init_t g_disk_init;
74static g_fini_t g_disk_fini;
75static g_start_t g_disk_start;
76static g_ioctl_t g_disk_ioctl;
77static g_dumpconf_t g_disk_dumpconf;
78static g_provgone_t g_disk_providergone;
79
80static struct g_class g_disk_class = {
81 .name = "DISK",
82 .version = G_VERSION,
83 .init = g_disk_init,
84 .fini = g_disk_fini,
85 .start = g_disk_start,
86 .access = g_disk_access,
87 .ioctl = g_disk_ioctl,
88 .providergone = g_disk_providergone,
89 .dumpconf = g_disk_dumpconf,
90};
91
92SYSCTL_DECL(_kern_geom);
93static SYSCTL_NODE(_kern_geom, OID_AUTO, disk, CTLFLAG_RW, 0,
94 "GEOM_DISK stuff");
95
96static void
97g_disk_init(struct g_class *mp __unused)
98{
99
100 mtx_init(&g_disk_done_mtx, "g_disk_done", NULL, MTX_DEF);
101}
102
103static void
104g_disk_fini(struct g_class *mp __unused)
105{
106
107 mtx_destroy(&g_disk_done_mtx);
108}
109
110DECLARE_GEOM_CLASS(g_disk_class, g_disk);
111
112static void __inline
113g_disk_lock_giant(struct disk *dp)
114{
115
116 if (dp->d_flags & DISKFLAG_NEEDSGIANT)
117 mtx_lock(&Giant);
118}
119
120static void __inline
121g_disk_unlock_giant(struct disk *dp)
122{
123
124 if (dp->d_flags & DISKFLAG_NEEDSGIANT)
125 mtx_unlock(&Giant);
126}
127
128static int
129g_disk_access(struct g_provider *pp, int r, int w, int e)
130{
131 struct disk *dp;
132 struct g_disk_softc *sc;
133 int error;
134
135 g_trace(G_T_ACCESS, "g_disk_access(%s, %d, %d, %d)",
136 pp->name, r, w, e);
137 g_topology_assert();
138 sc = pp->geom->softc;
139 if (sc == NULL || (dp = sc->dp) == NULL || dp->d_destroyed) {
140 /*
141 * Allow decreasing access count even if disk is not
142 * avaliable anymore.
143 */
144 if (r <= 0 && w <= 0 && e <= 0)
145 return (0);
146 return (ENXIO);
147 }
148 r += pp->acr;
149 w += pp->acw;
150 e += pp->ace;
151 error = 0;
152 if ((pp->acr + pp->acw + pp->ace) == 0 && (r + w + e) > 0) {
153 if (dp->d_open != NULL) {
154 g_disk_lock_giant(dp);
155 error = dp->d_open(dp);
156 if (bootverbose && error != 0)
157 printf("Opened disk %s -> %d\n",
158 pp->name, error);
159 g_disk_unlock_giant(dp);
160 }
161 pp->mediasize = dp->d_mediasize;
162 pp->sectorsize = dp->d_sectorsize;
163 if (dp->d_flags & DISKFLAG_CANDELETE)
164 pp->flags |= G_PF_CANDELETE;
165 else
166 pp->flags &= ~G_PF_CANDELETE;
167 pp->stripeoffset = dp->d_stripeoffset;
168 pp->stripesize = dp->d_stripesize;
169 dp->d_flags |= DISKFLAG_OPEN;
170 if (dp->d_maxsize == 0) {
171 printf("WARNING: Disk drive %s%d has no d_maxsize\n",
172 dp->d_name, dp->d_unit);
173 dp->d_maxsize = DFLTPHYS;
174 }
175 } else if ((pp->acr + pp->acw + pp->ace) > 0 && (r + w + e) == 0) {
176 if (dp->d_close != NULL) {
177 g_disk_lock_giant(dp);
178 error = dp->d_close(dp);
179 if (error != 0)
180 printf("Closed disk %s -> %d\n",
181 pp->name, error);
182 g_disk_unlock_giant(dp);
183 }
184 sc->state = G_STATE_ACTIVE;
185 if (sc->led[0] != 0)
186 led_set(sc->led, "0");
187 dp->d_flags &= ~DISKFLAG_OPEN;
188 }
189 return (error);
190}
191
192static void
193g_disk_kerneldump(struct bio *bp, struct disk *dp)
194{
195 struct g_kerneldump *gkd;
196 struct g_geom *gp;
197
198 gkd = (struct g_kerneldump*)bp->bio_data;
199 gp = bp->bio_to->geom;
200 g_trace(G_T_TOPOLOGY, "g_disk_kernedump(%s, %jd, %jd)",
201 gp->name, (intmax_t)gkd->offset, (intmax_t)gkd->length);
202 if (dp->d_dump == NULL) {
203 g_io_deliver(bp, ENODEV);
204 return;
205 }
206 gkd->di.dumper = dp->d_dump;
207 gkd->di.priv = dp;
208 gkd->di.blocksize = dp->d_sectorsize;
209 gkd->di.maxiosize = dp->d_maxsize;
210 gkd->di.mediaoffset = gkd->offset;
211 if ((gkd->offset + gkd->length) > dp->d_mediasize)
212 gkd->length = dp->d_mediasize - gkd->offset;
213 gkd->di.mediasize = gkd->length;
214 g_io_deliver(bp, 0);
215}
216
217static void
218g_disk_setstate(struct bio *bp, struct g_disk_softc *sc)
219{
220 const char *cmd;
221
222 memcpy(&sc->state, bp->bio_data, sizeof(sc->state));
223 if (sc->led[0] != 0) {
224 switch (sc->state) {
225 case G_STATE_FAILED:
226 cmd = "1";
227 break;
228 case G_STATE_REBUILD:
229 cmd = "f5";
230 break;
231 case G_STATE_RESYNC:
232 cmd = "f1";
233 break;
234 default:
235 cmd = "0";
236 break;
237 }
238 led_set(sc->led, cmd);
239 }
240 g_io_deliver(bp, 0);
241}
242
243static void
244g_disk_done(struct bio *bp)
245{
246 struct bio *bp2;
247 struct disk *dp;
248 struct g_disk_softc *sc;
249
250 /* See "notes" for why we need a mutex here */
251 /* XXX: will witness accept a mix of Giant/unGiant drivers here ? */
252 mtx_lock(&g_disk_done_mtx);
253 bp->bio_completed = bp->bio_length - bp->bio_resid;
254
255 bp2 = bp->bio_parent;
256 if (bp2->bio_error == 0)
257 bp2->bio_error = bp->bio_error;
258 bp2->bio_completed += bp->bio_completed;
259 if ((bp->bio_cmd & (BIO_READ|BIO_WRITE|BIO_DELETE)) != 0 &&
260 (sc = bp2->bio_to->geom->softc) != NULL &&
261 (dp = sc->dp) != NULL) {
262 devstat_end_transaction_bio(dp->d_devstat, bp);
263 }
264 g_destroy_bio(bp);
265 bp2->bio_inbed++;
266 if (bp2->bio_children == bp2->bio_inbed) {
267 bp2->bio_resid = bp2->bio_bcount - bp2->bio_completed;
268 g_io_deliver(bp2, bp2->bio_error);
269 }
270 mtx_unlock(&g_disk_done_mtx);
271}
272
273static int
274g_disk_ioctl(struct g_provider *pp, u_long cmd, void * data, int fflag, struct thread *td)
275{
276 struct g_geom *gp;
277 struct disk *dp;
278 struct g_disk_softc *sc;
279 int error;
280
281 gp = pp->geom;
282 sc = gp->softc;
283 dp = sc->dp;
284
285 if (dp->d_ioctl == NULL)
286 return (ENOIOCTL);
287 g_disk_lock_giant(dp);
288 error = dp->d_ioctl(dp, cmd, data, fflag, td);
289 g_disk_unlock_giant(dp);
290 return (error);
291}
292
293static void
294g_disk_start(struct bio *bp)
295{
296 struct bio *bp2, *bp3;
297 struct disk *dp;
298 struct g_disk_softc *sc;
299 int error;
300 off_t off;
301
302 sc = bp->bio_to->geom->softc;
303 if (sc == NULL || (dp = sc->dp) == NULL || dp->d_destroyed) {
304 g_io_deliver(bp, ENXIO);
305 return;
306 }
307 error = EJUSTRETURN;
308 switch(bp->bio_cmd) {
309 case BIO_DELETE:
310 if (!(dp->d_flags & DISKFLAG_CANDELETE)) {
311 error = EOPNOTSUPP;
312 break;
313 }
314 /* fall-through */
315 case BIO_READ:
316 case BIO_WRITE:
317 off = 0;
318 bp3 = NULL;
319 bp2 = g_clone_bio(bp);
320 if (bp2 == NULL) {
321 error = ENOMEM;
322 break;
323 }
324 do {
325 bp2->bio_offset += off;
326 bp2->bio_length -= off;
327 bp2->bio_data += off;
328 if (bp2->bio_length > dp->d_maxsize) {
329 /*
330 * XXX: If we have a stripesize we should really
331 * use it here.
332 */
333 bp2->bio_length = dp->d_maxsize;
334 off += dp->d_maxsize;
335 /*
336 * To avoid a race, we need to grab the next bio
337 * before we schedule this one. See "notes".
338 */
339 bp3 = g_clone_bio(bp);
340 if (bp3 == NULL)
341 bp->bio_error = ENOMEM;
342 }
343 bp2->bio_done = g_disk_done;
344 bp2->bio_pblkno = bp2->bio_offset / dp->d_sectorsize;
345 bp2->bio_bcount = bp2->bio_length;
346 bp2->bio_disk = dp;
347 devstat_start_transaction_bio(dp->d_devstat, bp2);
348 g_disk_lock_giant(dp);
349 dp->d_strategy(bp2);
350 g_disk_unlock_giant(dp);
351 bp2 = bp3;
352 bp3 = NULL;
353 } while (bp2 != NULL);
354 break;
355 case BIO_GETATTR:
356 /* Give the driver a chance to override */
357 if (dp->d_getattr != NULL) {
358 if (bp->bio_disk == NULL)
359 bp->bio_disk = dp;
360 error = dp->d_getattr(bp);
361 if (error != -1)
362 break;
363 error = EJUSTRETURN;
364 }
365 if (g_handleattr_int(bp, "GEOM::candelete",
366 (dp->d_flags & DISKFLAG_CANDELETE) != 0))
367 break;
368 else if (g_handleattr_int(bp, "GEOM::fwsectors",
369 dp->d_fwsectors))
370 break;
371 else if (g_handleattr_int(bp, "GEOM::fwheads", dp->d_fwheads))
372 break;
373 else if (g_handleattr_off_t(bp, "GEOM::frontstuff", 0))
374 break;
375 else if (g_handleattr_str(bp, "GEOM::ident", dp->d_ident))
376 break;
377 else if (g_handleattr(bp, "GEOM::hba_vendor",
378 &dp->d_hba_vendor, 2))
379 break;
380 else if (g_handleattr(bp, "GEOM::hba_device",
381 &dp->d_hba_device, 2))
382 break;
383 else if (g_handleattr(bp, "GEOM::hba_subvendor",
384 &dp->d_hba_subvendor, 2))
385 break;
386 else if (g_handleattr(bp, "GEOM::hba_subdevice",
387 &dp->d_hba_subdevice, 2))
388 break;
389 else if (!strcmp(bp->bio_attribute, "GEOM::kerneldump"))
390 g_disk_kerneldump(bp, dp);
391 else if (!strcmp(bp->bio_attribute, "GEOM::setstate"))
392 g_disk_setstate(bp, sc);
393 else
394 error = ENOIOCTL;
395 break;
396 case BIO_FLUSH:
397 g_trace(G_T_TOPOLOGY, "g_disk_flushcache(%s)",
398 bp->bio_to->name);
399 if (!(dp->d_flags & DISKFLAG_CANFLUSHCACHE)) {
400 error = EOPNOTSUPP;
401 break;
402 }
403 bp2 = g_clone_bio(bp);
404 if (bp2 == NULL) {
405 g_io_deliver(bp, ENOMEM);
406 return;
407 }
408 bp2->bio_done = g_disk_done;
409 bp2->bio_disk = dp;
410 g_disk_lock_giant(dp);
411 dp->d_strategy(bp2);
412 g_disk_unlock_giant(dp);
413 break;
414 default:
415 error = EOPNOTSUPP;
416 break;
417 }
418 if (error != EJUSTRETURN)
419 g_io_deliver(bp, error);
420 return;
421}
422
423static void
424g_disk_dumpconf(struct sbuf *sb, const char *indent, struct g_geom *gp, struct g_consumer *cp, struct g_provider *pp)
425{
426 struct disk *dp;
427 struct g_disk_softc *sc;
428
429 sc = gp->softc;
430 if (sc == NULL || (dp = sc->dp) == NULL)
431 return;
432 if (indent == NULL) {
433 sbuf_printf(sb, " hd %u", dp->d_fwheads);
434 sbuf_printf(sb, " sc %u", dp->d_fwsectors);
435 return;
436 }
437 if (pp != NULL) {
438 sbuf_printf(sb, "%s<fwheads>%u</fwheads>\n",
439 indent, dp->d_fwheads);
440 sbuf_printf(sb, "%s<fwsectors>%u</fwsectors>\n",
441 indent, dp->d_fwsectors);
442 sbuf_printf(sb, "%s<ident>%s</ident>\n", indent, dp->d_ident);
443 sbuf_printf(sb, "%s<descr>%s</descr>\n", indent, dp->d_descr);
444 }
445}
446
447static void
448g_disk_create(void *arg, int flag)
449{
450 struct g_geom *gp;
451 struct g_provider *pp;
452 struct disk *dp;
453 struct g_disk_softc *sc;
454 char tmpstr[80];
455
456 if (flag == EV_CANCEL)
457 return;
458 g_topology_assert();
459 dp = arg;
460 sc = g_malloc(sizeof(*sc), M_WAITOK | M_ZERO);
461 sc->dp = dp;
462 gp = g_new_geomf(&g_disk_class, "%s%d", dp->d_name, dp->d_unit);
463 gp->softc = sc;
464 pp = g_new_providerf(gp, "%s", gp->name);
465 pp->mediasize = dp->d_mediasize;
466 pp->sectorsize = dp->d_sectorsize;
467 if (dp->d_flags & DISKFLAG_CANDELETE)
468 pp->flags |= G_PF_CANDELETE;
469 pp->stripeoffset = dp->d_stripeoffset;
470 pp->stripesize = dp->d_stripesize;
471 if (bootverbose)
472 printf("GEOM: new disk %s\n", gp->name);
473 sysctl_ctx_init(&sc->sysctl_ctx);
474 snprintf(tmpstr, sizeof(tmpstr), "GEOM disk %s", gp->name);
475 sc->sysctl_tree = SYSCTL_ADD_NODE(&sc->sysctl_ctx,
476 SYSCTL_STATIC_CHILDREN(_kern_geom_disk), OID_AUTO, gp->name,
477 CTLFLAG_RD, 0, tmpstr);
478 if (sc->sysctl_tree != NULL) {
479 snprintf(tmpstr, sizeof(tmpstr),
480 "kern.geom.disk.%s.led", gp->name);
481 TUNABLE_STR_FETCH(tmpstr, sc->led, sizeof(sc->led));
482 SYSCTL_ADD_STRING(&sc->sysctl_ctx,
483 SYSCTL_CHILDREN(sc->sysctl_tree), OID_AUTO, "led",
484 CTLFLAG_RW | CTLFLAG_TUN, sc->led, sizeof(sc->led),
485 "LED name");
486 }
487 pp->private = sc;
488 dp->d_geom = gp;
489 g_error_provider(pp, 0);
490}
491
492/*
493 * We get this callback after all of the consumers have gone away, and just
494 * before the provider is freed. If the disk driver provided a d_gone
495 * callback, let them know that it is okay to free resources -- they won't
496 * be getting any more accesses from GEOM.
497 */
498static void
499g_disk_providergone(struct g_provider *pp)
500{
501 struct disk *dp;
502 struct g_disk_softc *sc;
503
504 sc = (struct g_disk_softc *)pp->geom->softc;
505
506 /*
507 * If the softc is already NULL, then we've probably been through
508 * g_disk_destroy already; there is nothing for us to do anyway.
509 */
510 if (sc == NULL)
511 return;
512
513 dp = sc->dp;
514
515 if (dp->d_gone != NULL)
516 dp->d_gone(dp);
517}
518
519static void
520g_disk_destroy(void *ptr, int flag)
521{
522 struct disk *dp;
523 struct g_geom *gp;
524 struct g_disk_softc *sc;
525
526 g_topology_assert();
527 dp = ptr;
528 gp = dp->d_geom;
529 if (gp != NULL) {
530 sc = gp->softc;
531 if (sc->sysctl_tree != NULL) {
532 sysctl_ctx_free(&sc->sysctl_ctx);
533 sc->sysctl_tree = NULL;
534 }
535 if (sc->led[0] != 0) {
536 led_set(sc->led, "0");
537 sc->led[0] = 0;
538 }
539 g_free(sc);
540 gp->softc = NULL;
541 g_wither_geom(gp, ENXIO);
542 }
543 g_free(dp);
544}
545
546/*
547 * We only allow printable characters in disk ident,
548 * the rest is converted to 'x<HH>'.
549 */
550static void
551g_disk_ident_adjust(char *ident, size_t size)
552{
553 char *p, tmp[4], newid[DISK_IDENT_SIZE];
554
555 newid[0] = '\0';
556 for (p = ident; *p != '\0'; p++) {
557 if (isprint(*p)) {
558 tmp[0] = *p;
559 tmp[1] = '\0';
560 } else {
561 snprintf(tmp, sizeof(tmp), "x%02hhx",
562 *(unsigned char *)p);
563 }
564 if (strlcat(newid, tmp, sizeof(newid)) >= sizeof(newid))
565 break;
566 }
567 bzero(ident, size);
568 strlcpy(ident, newid, size);
569}
570
571struct disk *
572disk_alloc(void)
573{
574
575 return (g_malloc(sizeof(struct disk), M_WAITOK | M_ZERO));
576}
577
578void
579disk_create(struct disk *dp, int version)
580{
581
582 if (version != DISK_VERSION_02) {
583 printf("WARNING: Attempt to add disk %s%d %s",
584 dp->d_name, dp->d_unit,
585 " using incompatible ABI version of disk(9)\n");
586 printf("WARNING: Ignoring disk %s%d\n",
587 dp->d_name, dp->d_unit);
588 return;
589 }
590 KASSERT(dp->d_strategy != NULL, ("disk_create need d_strategy"));
591 KASSERT(dp->d_name != NULL, ("disk_create need d_name"));
592 KASSERT(*dp->d_name != 0, ("disk_create need d_name"));
593 KASSERT(strlen(dp->d_name) < SPECNAMELEN - 4, ("disk name too long"));
594 if (dp->d_devstat == NULL)
595 dp->d_devstat = devstat_new_entry(dp->d_name, dp->d_unit,
596 dp->d_sectorsize, DEVSTAT_ALL_SUPPORTED,
597 DEVSTAT_TYPE_DIRECT, DEVSTAT_PRIORITY_MAX);
598 dp->d_geom = NULL;
599 g_disk_ident_adjust(dp->d_ident, sizeof(dp->d_ident));
600 g_post_event(g_disk_create, dp, M_WAITOK, dp, NULL);
601}
602
603void
604disk_destroy(struct disk *dp)
605{
606
607 g_cancel_event(dp);
608 dp->d_destroyed = 1;
609 if (dp->d_devstat != NULL)
610 devstat_remove_entry(dp->d_devstat);
611 g_post_event(g_disk_destroy, dp, M_WAITOK, NULL);
612}
613
614void
615disk_gone(struct disk *dp)
616{
617 struct g_geom *gp;
618 struct g_provider *pp;
619
620 gp = dp->d_geom;
621 if (gp != NULL)
622 LIST_FOREACH(pp, &gp->provider, provider)
623 g_wither_provider(pp, ENXIO);
624}
625
626void
627disk_attr_changed(struct disk *dp, const char *attr, int flag)
628{
629 struct g_geom *gp;
630 struct g_provider *pp;
631
632 gp = dp->d_geom;
633 if (gp != NULL)
634 LIST_FOREACH(pp, &gp->provider, provider)
635 (void)g_attr_changed(pp, attr, flag);
636}
637
638static void
639g_kern_disks(void *p, int flag __unused)
640{
641 struct sbuf *sb;
642 struct g_geom *gp;
643 char *sp;
644
645 sb = p;
646 sp = "";
647 g_topology_assert();
648 LIST_FOREACH(gp, &g_disk_class.geom, geom) {
649 sbuf_printf(sb, "%s%s", sp, gp->name);
650 sp = " ";
651 }
652 sbuf_finish(sb);
653}
654
655static int
656sysctl_disks(SYSCTL_HANDLER_ARGS)
657{
658 int error;
659 struct sbuf *sb;
660
661 sb = sbuf_new_auto();
662 g_waitfor_event(g_kern_disks, sb, M_WAITOK, NULL);
663 error = SYSCTL_OUT(req, sbuf_data(sb), sbuf_len(sb) + 1);
664 sbuf_delete(sb);
665 return error;
666}
667
668SYSCTL_PROC(_kern, OID_AUTO, disks,
669 CTLTYPE_STRING | CTLFLAG_RD | CTLFLAG_MPSAFE, NULL, 0,
670 sysctl_disks, "A", "names of available disks");
2 * Copyright (c) 2002 Poul-Henning Kamp
3 * Copyright (c) 2002 Networks Associates Technology, Inc.
4 * All rights reserved.
5 *
6 * This software was developed for the FreeBSD Project by Poul-Henning Kamp
7 * and NAI Labs, the Security Research Division of Network Associates, Inc.
8 * under DARPA/SPAWAR contract N66001-01-C-8035 ("CBOSS"), as part of the
9 * DARPA CHATS research program.
10 *
11 * Redistribution and use in source and binary forms, with or without
12 * modification, are permitted provided that the following conditions
13 * are met:
14 * 1. Redistributions of source code must retain the above copyright
15 * notice, this list of conditions and the following disclaimer.
16 * 2. Redistributions in binary form must reproduce the above copyright
17 * notice, this list of conditions and the following disclaimer in the
18 * documentation and/or other materials provided with the distribution.
19 * 3. The names of the authors may not be used to endorse or promote
20 * products derived from this software without specific prior written
21 * permission.
22 *
23 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
24 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
25 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
26 * ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
27 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
28 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
29 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
30 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
31 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
32 * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
33 * SUCH DAMAGE.
34 */
35
36#include <sys/cdefs.h>
37__FBSDID("$FreeBSD: head/sys/geom/geom_disk.c 237648 2012-06-27 16:05:09Z ken $");
38
39#include "opt_geom.h"
40
41#include <sys/param.h>
42#include <sys/systm.h>
43#include <sys/kernel.h>
44#include <sys/sysctl.h>
45#include <sys/bio.h>
46#include <sys/ctype.h>
47#include <sys/fcntl.h>
48#include <sys/malloc.h>
49#include <sys/sbuf.h>
50#include <sys/sysctl.h>
51#include <sys/devicestat.h>
52#include <machine/md_var.h>
53
54#include <sys/lock.h>
55#include <sys/mutex.h>
56#include <geom/geom.h>
57#include <geom/geom_disk.h>
58#include <geom/geom_int.h>
59
60#include <dev/led/led.h>
61
62struct g_disk_softc {
63 struct disk *dp;
64 struct sysctl_ctx_list sysctl_ctx;
65 struct sysctl_oid *sysctl_tree;
66 char led[64];
67 uint32_t state;
68};
69
70static struct mtx g_disk_done_mtx;
71
72static g_access_t g_disk_access;
73static g_init_t g_disk_init;
74static g_fini_t g_disk_fini;
75static g_start_t g_disk_start;
76static g_ioctl_t g_disk_ioctl;
77static g_dumpconf_t g_disk_dumpconf;
78static g_provgone_t g_disk_providergone;
79
80static struct g_class g_disk_class = {
81 .name = "DISK",
82 .version = G_VERSION,
83 .init = g_disk_init,
84 .fini = g_disk_fini,
85 .start = g_disk_start,
86 .access = g_disk_access,
87 .ioctl = g_disk_ioctl,
88 .providergone = g_disk_providergone,
89 .dumpconf = g_disk_dumpconf,
90};
91
92SYSCTL_DECL(_kern_geom);
93static SYSCTL_NODE(_kern_geom, OID_AUTO, disk, CTLFLAG_RW, 0,
94 "GEOM_DISK stuff");
95
96static void
97g_disk_init(struct g_class *mp __unused)
98{
99
100 mtx_init(&g_disk_done_mtx, "g_disk_done", NULL, MTX_DEF);
101}
102
103static void
104g_disk_fini(struct g_class *mp __unused)
105{
106
107 mtx_destroy(&g_disk_done_mtx);
108}
109
110DECLARE_GEOM_CLASS(g_disk_class, g_disk);
111
112static void __inline
113g_disk_lock_giant(struct disk *dp)
114{
115
116 if (dp->d_flags & DISKFLAG_NEEDSGIANT)
117 mtx_lock(&Giant);
118}
119
120static void __inline
121g_disk_unlock_giant(struct disk *dp)
122{
123
124 if (dp->d_flags & DISKFLAG_NEEDSGIANT)
125 mtx_unlock(&Giant);
126}
127
128static int
129g_disk_access(struct g_provider *pp, int r, int w, int e)
130{
131 struct disk *dp;
132 struct g_disk_softc *sc;
133 int error;
134
135 g_trace(G_T_ACCESS, "g_disk_access(%s, %d, %d, %d)",
136 pp->name, r, w, e);
137 g_topology_assert();
138 sc = pp->geom->softc;
139 if (sc == NULL || (dp = sc->dp) == NULL || dp->d_destroyed) {
140 /*
141 * Allow decreasing access count even if disk is not
142 * avaliable anymore.
143 */
144 if (r <= 0 && w <= 0 && e <= 0)
145 return (0);
146 return (ENXIO);
147 }
148 r += pp->acr;
149 w += pp->acw;
150 e += pp->ace;
151 error = 0;
152 if ((pp->acr + pp->acw + pp->ace) == 0 && (r + w + e) > 0) {
153 if (dp->d_open != NULL) {
154 g_disk_lock_giant(dp);
155 error = dp->d_open(dp);
156 if (bootverbose && error != 0)
157 printf("Opened disk %s -> %d\n",
158 pp->name, error);
159 g_disk_unlock_giant(dp);
160 }
161 pp->mediasize = dp->d_mediasize;
162 pp->sectorsize = dp->d_sectorsize;
163 if (dp->d_flags & DISKFLAG_CANDELETE)
164 pp->flags |= G_PF_CANDELETE;
165 else
166 pp->flags &= ~G_PF_CANDELETE;
167 pp->stripeoffset = dp->d_stripeoffset;
168 pp->stripesize = dp->d_stripesize;
169 dp->d_flags |= DISKFLAG_OPEN;
170 if (dp->d_maxsize == 0) {
171 printf("WARNING: Disk drive %s%d has no d_maxsize\n",
172 dp->d_name, dp->d_unit);
173 dp->d_maxsize = DFLTPHYS;
174 }
175 } else if ((pp->acr + pp->acw + pp->ace) > 0 && (r + w + e) == 0) {
176 if (dp->d_close != NULL) {
177 g_disk_lock_giant(dp);
178 error = dp->d_close(dp);
179 if (error != 0)
180 printf("Closed disk %s -> %d\n",
181 pp->name, error);
182 g_disk_unlock_giant(dp);
183 }
184 sc->state = G_STATE_ACTIVE;
185 if (sc->led[0] != 0)
186 led_set(sc->led, "0");
187 dp->d_flags &= ~DISKFLAG_OPEN;
188 }
189 return (error);
190}
191
192static void
193g_disk_kerneldump(struct bio *bp, struct disk *dp)
194{
195 struct g_kerneldump *gkd;
196 struct g_geom *gp;
197
198 gkd = (struct g_kerneldump*)bp->bio_data;
199 gp = bp->bio_to->geom;
200 g_trace(G_T_TOPOLOGY, "g_disk_kernedump(%s, %jd, %jd)",
201 gp->name, (intmax_t)gkd->offset, (intmax_t)gkd->length);
202 if (dp->d_dump == NULL) {
203 g_io_deliver(bp, ENODEV);
204 return;
205 }
206 gkd->di.dumper = dp->d_dump;
207 gkd->di.priv = dp;
208 gkd->di.blocksize = dp->d_sectorsize;
209 gkd->di.maxiosize = dp->d_maxsize;
210 gkd->di.mediaoffset = gkd->offset;
211 if ((gkd->offset + gkd->length) > dp->d_mediasize)
212 gkd->length = dp->d_mediasize - gkd->offset;
213 gkd->di.mediasize = gkd->length;
214 g_io_deliver(bp, 0);
215}
216
217static void
218g_disk_setstate(struct bio *bp, struct g_disk_softc *sc)
219{
220 const char *cmd;
221
222 memcpy(&sc->state, bp->bio_data, sizeof(sc->state));
223 if (sc->led[0] != 0) {
224 switch (sc->state) {
225 case G_STATE_FAILED:
226 cmd = "1";
227 break;
228 case G_STATE_REBUILD:
229 cmd = "f5";
230 break;
231 case G_STATE_RESYNC:
232 cmd = "f1";
233 break;
234 default:
235 cmd = "0";
236 break;
237 }
238 led_set(sc->led, cmd);
239 }
240 g_io_deliver(bp, 0);
241}
242
243static void
244g_disk_done(struct bio *bp)
245{
246 struct bio *bp2;
247 struct disk *dp;
248 struct g_disk_softc *sc;
249
250 /* See "notes" for why we need a mutex here */
251 /* XXX: will witness accept a mix of Giant/unGiant drivers here ? */
252 mtx_lock(&g_disk_done_mtx);
253 bp->bio_completed = bp->bio_length - bp->bio_resid;
254
255 bp2 = bp->bio_parent;
256 if (bp2->bio_error == 0)
257 bp2->bio_error = bp->bio_error;
258 bp2->bio_completed += bp->bio_completed;
259 if ((bp->bio_cmd & (BIO_READ|BIO_WRITE|BIO_DELETE)) != 0 &&
260 (sc = bp2->bio_to->geom->softc) != NULL &&
261 (dp = sc->dp) != NULL) {
262 devstat_end_transaction_bio(dp->d_devstat, bp);
263 }
264 g_destroy_bio(bp);
265 bp2->bio_inbed++;
266 if (bp2->bio_children == bp2->bio_inbed) {
267 bp2->bio_resid = bp2->bio_bcount - bp2->bio_completed;
268 g_io_deliver(bp2, bp2->bio_error);
269 }
270 mtx_unlock(&g_disk_done_mtx);
271}
272
273static int
274g_disk_ioctl(struct g_provider *pp, u_long cmd, void * data, int fflag, struct thread *td)
275{
276 struct g_geom *gp;
277 struct disk *dp;
278 struct g_disk_softc *sc;
279 int error;
280
281 gp = pp->geom;
282 sc = gp->softc;
283 dp = sc->dp;
284
285 if (dp->d_ioctl == NULL)
286 return (ENOIOCTL);
287 g_disk_lock_giant(dp);
288 error = dp->d_ioctl(dp, cmd, data, fflag, td);
289 g_disk_unlock_giant(dp);
290 return (error);
291}
292
293static void
294g_disk_start(struct bio *bp)
295{
296 struct bio *bp2, *bp3;
297 struct disk *dp;
298 struct g_disk_softc *sc;
299 int error;
300 off_t off;
301
302 sc = bp->bio_to->geom->softc;
303 if (sc == NULL || (dp = sc->dp) == NULL || dp->d_destroyed) {
304 g_io_deliver(bp, ENXIO);
305 return;
306 }
307 error = EJUSTRETURN;
308 switch(bp->bio_cmd) {
309 case BIO_DELETE:
310 if (!(dp->d_flags & DISKFLAG_CANDELETE)) {
311 error = EOPNOTSUPP;
312 break;
313 }
314 /* fall-through */
315 case BIO_READ:
316 case BIO_WRITE:
317 off = 0;
318 bp3 = NULL;
319 bp2 = g_clone_bio(bp);
320 if (bp2 == NULL) {
321 error = ENOMEM;
322 break;
323 }
324 do {
325 bp2->bio_offset += off;
326 bp2->bio_length -= off;
327 bp2->bio_data += off;
328 if (bp2->bio_length > dp->d_maxsize) {
329 /*
330 * XXX: If we have a stripesize we should really
331 * use it here.
332 */
333 bp2->bio_length = dp->d_maxsize;
334 off += dp->d_maxsize;
335 /*
336 * To avoid a race, we need to grab the next bio
337 * before we schedule this one. See "notes".
338 */
339 bp3 = g_clone_bio(bp);
340 if (bp3 == NULL)
341 bp->bio_error = ENOMEM;
342 }
343 bp2->bio_done = g_disk_done;
344 bp2->bio_pblkno = bp2->bio_offset / dp->d_sectorsize;
345 bp2->bio_bcount = bp2->bio_length;
346 bp2->bio_disk = dp;
347 devstat_start_transaction_bio(dp->d_devstat, bp2);
348 g_disk_lock_giant(dp);
349 dp->d_strategy(bp2);
350 g_disk_unlock_giant(dp);
351 bp2 = bp3;
352 bp3 = NULL;
353 } while (bp2 != NULL);
354 break;
355 case BIO_GETATTR:
356 /* Give the driver a chance to override */
357 if (dp->d_getattr != NULL) {
358 if (bp->bio_disk == NULL)
359 bp->bio_disk = dp;
360 error = dp->d_getattr(bp);
361 if (error != -1)
362 break;
363 error = EJUSTRETURN;
364 }
365 if (g_handleattr_int(bp, "GEOM::candelete",
366 (dp->d_flags & DISKFLAG_CANDELETE) != 0))
367 break;
368 else if (g_handleattr_int(bp, "GEOM::fwsectors",
369 dp->d_fwsectors))
370 break;
371 else if (g_handleattr_int(bp, "GEOM::fwheads", dp->d_fwheads))
372 break;
373 else if (g_handleattr_off_t(bp, "GEOM::frontstuff", 0))
374 break;
375 else if (g_handleattr_str(bp, "GEOM::ident", dp->d_ident))
376 break;
377 else if (g_handleattr(bp, "GEOM::hba_vendor",
378 &dp->d_hba_vendor, 2))
379 break;
380 else if (g_handleattr(bp, "GEOM::hba_device",
381 &dp->d_hba_device, 2))
382 break;
383 else if (g_handleattr(bp, "GEOM::hba_subvendor",
384 &dp->d_hba_subvendor, 2))
385 break;
386 else if (g_handleattr(bp, "GEOM::hba_subdevice",
387 &dp->d_hba_subdevice, 2))
388 break;
389 else if (!strcmp(bp->bio_attribute, "GEOM::kerneldump"))
390 g_disk_kerneldump(bp, dp);
391 else if (!strcmp(bp->bio_attribute, "GEOM::setstate"))
392 g_disk_setstate(bp, sc);
393 else
394 error = ENOIOCTL;
395 break;
396 case BIO_FLUSH:
397 g_trace(G_T_TOPOLOGY, "g_disk_flushcache(%s)",
398 bp->bio_to->name);
399 if (!(dp->d_flags & DISKFLAG_CANFLUSHCACHE)) {
400 error = EOPNOTSUPP;
401 break;
402 }
403 bp2 = g_clone_bio(bp);
404 if (bp2 == NULL) {
405 g_io_deliver(bp, ENOMEM);
406 return;
407 }
408 bp2->bio_done = g_disk_done;
409 bp2->bio_disk = dp;
410 g_disk_lock_giant(dp);
411 dp->d_strategy(bp2);
412 g_disk_unlock_giant(dp);
413 break;
414 default:
415 error = EOPNOTSUPP;
416 break;
417 }
418 if (error != EJUSTRETURN)
419 g_io_deliver(bp, error);
420 return;
421}
422
423static void
424g_disk_dumpconf(struct sbuf *sb, const char *indent, struct g_geom *gp, struct g_consumer *cp, struct g_provider *pp)
425{
426 struct disk *dp;
427 struct g_disk_softc *sc;
428
429 sc = gp->softc;
430 if (sc == NULL || (dp = sc->dp) == NULL)
431 return;
432 if (indent == NULL) {
433 sbuf_printf(sb, " hd %u", dp->d_fwheads);
434 sbuf_printf(sb, " sc %u", dp->d_fwsectors);
435 return;
436 }
437 if (pp != NULL) {
438 sbuf_printf(sb, "%s<fwheads>%u</fwheads>\n",
439 indent, dp->d_fwheads);
440 sbuf_printf(sb, "%s<fwsectors>%u</fwsectors>\n",
441 indent, dp->d_fwsectors);
442 sbuf_printf(sb, "%s<ident>%s</ident>\n", indent, dp->d_ident);
443 sbuf_printf(sb, "%s<descr>%s</descr>\n", indent, dp->d_descr);
444 }
445}
446
447static void
448g_disk_create(void *arg, int flag)
449{
450 struct g_geom *gp;
451 struct g_provider *pp;
452 struct disk *dp;
453 struct g_disk_softc *sc;
454 char tmpstr[80];
455
456 if (flag == EV_CANCEL)
457 return;
458 g_topology_assert();
459 dp = arg;
460 sc = g_malloc(sizeof(*sc), M_WAITOK | M_ZERO);
461 sc->dp = dp;
462 gp = g_new_geomf(&g_disk_class, "%s%d", dp->d_name, dp->d_unit);
463 gp->softc = sc;
464 pp = g_new_providerf(gp, "%s", gp->name);
465 pp->mediasize = dp->d_mediasize;
466 pp->sectorsize = dp->d_sectorsize;
467 if (dp->d_flags & DISKFLAG_CANDELETE)
468 pp->flags |= G_PF_CANDELETE;
469 pp->stripeoffset = dp->d_stripeoffset;
470 pp->stripesize = dp->d_stripesize;
471 if (bootverbose)
472 printf("GEOM: new disk %s\n", gp->name);
473 sysctl_ctx_init(&sc->sysctl_ctx);
474 snprintf(tmpstr, sizeof(tmpstr), "GEOM disk %s", gp->name);
475 sc->sysctl_tree = SYSCTL_ADD_NODE(&sc->sysctl_ctx,
476 SYSCTL_STATIC_CHILDREN(_kern_geom_disk), OID_AUTO, gp->name,
477 CTLFLAG_RD, 0, tmpstr);
478 if (sc->sysctl_tree != NULL) {
479 snprintf(tmpstr, sizeof(tmpstr),
480 "kern.geom.disk.%s.led", gp->name);
481 TUNABLE_STR_FETCH(tmpstr, sc->led, sizeof(sc->led));
482 SYSCTL_ADD_STRING(&sc->sysctl_ctx,
483 SYSCTL_CHILDREN(sc->sysctl_tree), OID_AUTO, "led",
484 CTLFLAG_RW | CTLFLAG_TUN, sc->led, sizeof(sc->led),
485 "LED name");
486 }
487 pp->private = sc;
488 dp->d_geom = gp;
489 g_error_provider(pp, 0);
490}
491
492/*
493 * We get this callback after all of the consumers have gone away, and just
494 * before the provider is freed. If the disk driver provided a d_gone
495 * callback, let them know that it is okay to free resources -- they won't
496 * be getting any more accesses from GEOM.
497 */
498static void
499g_disk_providergone(struct g_provider *pp)
500{
501 struct disk *dp;
502 struct g_disk_softc *sc;
503
504 sc = (struct g_disk_softc *)pp->geom->softc;
505
506 /*
507 * If the softc is already NULL, then we've probably been through
508 * g_disk_destroy already; there is nothing for us to do anyway.
509 */
510 if (sc == NULL)
511 return;
512
513 dp = sc->dp;
514
515 if (dp->d_gone != NULL)
516 dp->d_gone(dp);
517}
518
519static void
520g_disk_destroy(void *ptr, int flag)
521{
522 struct disk *dp;
523 struct g_geom *gp;
524 struct g_disk_softc *sc;
525
526 g_topology_assert();
527 dp = ptr;
528 gp = dp->d_geom;
529 if (gp != NULL) {
530 sc = gp->softc;
531 if (sc->sysctl_tree != NULL) {
532 sysctl_ctx_free(&sc->sysctl_ctx);
533 sc->sysctl_tree = NULL;
534 }
535 if (sc->led[0] != 0) {
536 led_set(sc->led, "0");
537 sc->led[0] = 0;
538 }
539 g_free(sc);
540 gp->softc = NULL;
541 g_wither_geom(gp, ENXIO);
542 }
543 g_free(dp);
544}
545
546/*
547 * We only allow printable characters in disk ident,
548 * the rest is converted to 'x<HH>'.
549 */
550static void
551g_disk_ident_adjust(char *ident, size_t size)
552{
553 char *p, tmp[4], newid[DISK_IDENT_SIZE];
554
555 newid[0] = '\0';
556 for (p = ident; *p != '\0'; p++) {
557 if (isprint(*p)) {
558 tmp[0] = *p;
559 tmp[1] = '\0';
560 } else {
561 snprintf(tmp, sizeof(tmp), "x%02hhx",
562 *(unsigned char *)p);
563 }
564 if (strlcat(newid, tmp, sizeof(newid)) >= sizeof(newid))
565 break;
566 }
567 bzero(ident, size);
568 strlcpy(ident, newid, size);
569}
570
571struct disk *
572disk_alloc(void)
573{
574
575 return (g_malloc(sizeof(struct disk), M_WAITOK | M_ZERO));
576}
577
578void
579disk_create(struct disk *dp, int version)
580{
581
582 if (version != DISK_VERSION_02) {
583 printf("WARNING: Attempt to add disk %s%d %s",
584 dp->d_name, dp->d_unit,
585 " using incompatible ABI version of disk(9)\n");
586 printf("WARNING: Ignoring disk %s%d\n",
587 dp->d_name, dp->d_unit);
588 return;
589 }
590 KASSERT(dp->d_strategy != NULL, ("disk_create need d_strategy"));
591 KASSERT(dp->d_name != NULL, ("disk_create need d_name"));
592 KASSERT(*dp->d_name != 0, ("disk_create need d_name"));
593 KASSERT(strlen(dp->d_name) < SPECNAMELEN - 4, ("disk name too long"));
594 if (dp->d_devstat == NULL)
595 dp->d_devstat = devstat_new_entry(dp->d_name, dp->d_unit,
596 dp->d_sectorsize, DEVSTAT_ALL_SUPPORTED,
597 DEVSTAT_TYPE_DIRECT, DEVSTAT_PRIORITY_MAX);
598 dp->d_geom = NULL;
599 g_disk_ident_adjust(dp->d_ident, sizeof(dp->d_ident));
600 g_post_event(g_disk_create, dp, M_WAITOK, dp, NULL);
601}
602
603void
604disk_destroy(struct disk *dp)
605{
606
607 g_cancel_event(dp);
608 dp->d_destroyed = 1;
609 if (dp->d_devstat != NULL)
610 devstat_remove_entry(dp->d_devstat);
611 g_post_event(g_disk_destroy, dp, M_WAITOK, NULL);
612}
613
614void
615disk_gone(struct disk *dp)
616{
617 struct g_geom *gp;
618 struct g_provider *pp;
619
620 gp = dp->d_geom;
621 if (gp != NULL)
622 LIST_FOREACH(pp, &gp->provider, provider)
623 g_wither_provider(pp, ENXIO);
624}
625
626void
627disk_attr_changed(struct disk *dp, const char *attr, int flag)
628{
629 struct g_geom *gp;
630 struct g_provider *pp;
631
632 gp = dp->d_geom;
633 if (gp != NULL)
634 LIST_FOREACH(pp, &gp->provider, provider)
635 (void)g_attr_changed(pp, attr, flag);
636}
637
638static void
639g_kern_disks(void *p, int flag __unused)
640{
641 struct sbuf *sb;
642 struct g_geom *gp;
643 char *sp;
644
645 sb = p;
646 sp = "";
647 g_topology_assert();
648 LIST_FOREACH(gp, &g_disk_class.geom, geom) {
649 sbuf_printf(sb, "%s%s", sp, gp->name);
650 sp = " ";
651 }
652 sbuf_finish(sb);
653}
654
655static int
656sysctl_disks(SYSCTL_HANDLER_ARGS)
657{
658 int error;
659 struct sbuf *sb;
660
661 sb = sbuf_new_auto();
662 g_waitfor_event(g_kern_disks, sb, M_WAITOK, NULL);
663 error = SYSCTL_OUT(req, sbuf_data(sb), sbuf_len(sb) + 1);
664 sbuf_delete(sb);
665 return error;
666}
667
668SYSCTL_PROC(_kern, OID_AUTO, disks,
669 CTLTYPE_STRING | CTLFLAG_RD | CTLFLAG_MPSAFE, NULL, 0,
670 sysctl_disks, "A", "names of available disks");