git.saurik.com Git - apple/xnu.git/blob - osfmk/mach/mach

1 /*

3 *

4 * @APPLE_OSREFERENCE_LICENSE_HEADER_START@

5 *

6 * This file contains Original Code and/or Modifications of Original Code

7 * as defined in and that are subject to the Apple Public Source License

8 * Version 2.0 (the 'License'). You may not use this file except in

9 * compliance with the License. The rights granted to you under the License

10 * may not be used to create, or enable the creation or redistribution of,

11 * unlawful or unlicensed copies of an Apple operating system, or to

12 * circumvent, violate, or enable the circumvention or violation of, any

13 * terms of an Apple operating system software license agreement.

14 *

15 * Please obtain a copy of the License at

16 * http://www.opensource.apple.com/apsl/ and read it before using this file.

17 *

18 * The Original Code and all software distributed under the License are

19 * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER

20 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,

21 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,

22 * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.

23 * Please see the License for the specific language governing rights and

24 * limitations under the License.

25 *

26 * @APPLE_OSREFERENCE_LICENSE_HEADER_END@

27 */

28 /*

29 * @OSF_FREE_COPYRIGHT@

30 */

31 /*

32 * Mach Operating System

35 *

36 * Permission to use, copy, modify and distribute this software and its

37 * documentation is hereby granted, provided that both the copyright

38 * notice and this permission notice appear in all copies of the

39 * software, derivative works or modified versions, and any portions

40 * thereof, and that both notices appear in supporting documentation.

41 *

42 * CARNEGIE MELLON ALLOWS FREE USE OF THIS SOFTWARE IN ITS "AS IS"

43 * CONDITION. CARNEGIE MELLON DISCLAIMS ANY LIABILITY OF ANY KIND FOR

44 * ANY DAMAGES WHATSOEVER RESULTING FROM THE USE OF THIS SOFTWARE.

45 *

46 * Carnegie Mellon requests users of this software to return to

47 *

48 * Software Distribution Coordinator or Software.Distribution@CS.CMU.EDU

49 * School of Computer Science

50 * Carnegie Mellon University

51 * Pittsburgh PA 15213-3890

52 *

53 * any improvements or extensions that they make and grant Carnegie Mellon

54 * the rights to redistribute these changes.

55 */

56 /*

57 */

58 /*

59 * File: mach/mach_port.defs

60 * Author: Rich Draves

61 *

62 * Exported kernel calls.

63 */

65 subsystem

66 #if KERNEL_SERVER

67 KernelServer

68 #endif /* KERNEL_SERVER */

69 mach_port 3200;

71 #if !KERNEL && !LIBSYSCALL_INTERFACE

72 UserPrefix _kernelrpc_;

73 #endif

75 #include <mach/std_types.defs>

76 #include <mach/mach_types.defs>

77 #include <mach_debug/mach_debug_types.defs>

79 type kobject_description_t = c_string[*:512];

81 /*

82 * Returns the set of port and port set names

83 * to which the target task has access, along with

84 * the type (set or port) for each name.

85 */

87 routine mach_port_names(

88 task : ipc_space_t;

89 out names : mach_port_name_array_t;

90 out types : mach_port_type_array_t);

92 /*

93 * Returns the type (set or port) for the port name

94 * within the target task. Also indicates whether

95 * there is a dead-name request for the name.

96 */

98 routine mach_port_type(

99 task : ipc_space_t;

100 name : mach_port_name_t;

101 out ptype : mach_port_type_t);

102

103 /*

104 * Changes the name by which a port (or port set) is known to

105 * the target task. The new name can't be in use. The

106 * old name becomes available for recycling.

107 *

108 * This interface is OBSOLETE and will always

109 * return KERN_NOT_SUPPORTED.

110 */

111

112 routine mach_port_rename(

113 task : ipc_space_t;

114 old_name : mach_port_name_t;

115 new_name : mach_port_name_t);

116

117 /*

118 * Allocates the specified kind of object, with the given name.

119 * The right must be one of

120 * MACH_PORT_RIGHT_RECEIVE

121 * MACH_PORT_RIGHT_PORT_SET

122 * MACH_PORT_RIGHT_DEAD_NAME

123 * New port sets are empty. New ports don't have any

124 * send/send-once rights or queued messages. The make-send

125 * count is zero and their queue limit is MACH_PORT_QLIMIT_DEFAULT.

126 * New sets, ports, and dead names have one user reference.

127 */

128

129 routine mach_port_allocate_name(

130 task : ipc_space_t;

131 right : mach_port_right_t;

132 name : mach_port_name_t);

133

134 /*

135 * Allocates the specified kind of object.

136 * The right must be one of

137 * MACH_PORT_RIGHT_RECEIVE

138 * MACH_PORT_RIGHT_PORT_SET

139 * MACH_PORT_RIGHT_DEAD_NAME

140 * Like port_allocate_name, but the kernel picks a name.

141 * It can use any name not associated with a right.

142 */

143

144 routine mach_port_allocate(

145 task : ipc_space_t;

146 right : mach_port_right_t;

147 out name : mach_port_name_t);

148

149 /*

150 * Destroys all rights associated with the name and makes it

151 * available for recycling immediately. The name can be a

152 * port (possibly with multiple user refs), a port set, or

153 * a dead name (again, with multiple user refs).

154 */

155

156 routine mach_port_destroy(

157 task : ipc_space_t;

158 name : mach_port_name_t);

159

160 /*

161 * Releases one send/send-once/dead-name user ref.

162 * Just like mach_port_mod_refs -1, but deduces the

163 * correct type of right. This allows a user task

164 * to release a ref for a port without worrying

165 * about whether the port has died or not.

166 */

167

168 routine mach_port_deallocate(

169 task : ipc_space_t;

170 name : mach_port_name_t);

171

172 /*

173 * A port set always has one user ref.

174 * A send-once right always has one user ref.

175 * A dead name always has one or more user refs.

176 * A send right always has one or more user refs.

177 * A receive right always has one user ref.

178 * The right must be one of

179 * MACH_PORT_RIGHT_RECEIVE

180 * MACH_PORT_RIGHT_PORT_SET

181 * MACH_PORT_RIGHT_DEAD_NAME

182 * MACH_PORT_RIGHT_SEND

183 * MACH_PORT_RIGHT_SEND_ONCE

184 */

185

186 routine mach_port_get_refs(

187 task : ipc_space_t;

188 name : mach_port_name_t;

189 right : mach_port_right_t;

190 out refs : mach_port_urefs_t);

191

192 /*

193 * The delta is a signed change to the task's

194 * user ref count for the right. Only dead names

195 * and send rights can have a positive delta.

196 * The resulting user ref count can't be negative.

197 * If it is zero, the right is deallocated.

198 * If the name isn't a composite right, it becomes

199 * available for recycling. The right must be one of

200 * MACH_PORT_RIGHT_RECEIVE

201 * MACH_PORT_RIGHT_PORT_SET

202 * MACH_PORT_RIGHT_DEAD_NAME

203 * MACH_PORT_RIGHT_SEND

204 * MACH_PORT_RIGHT_SEND_ONCE

205 */

206

207 routine mach_port_mod_refs(

208 task : ipc_space_t;

209 name : mach_port_name_t;

210 right : mach_port_right_t;

211 delta : mach_port_delta_t);

212

213 /*

214 * Peek at the message queue for the specified receive

215 * right and return info about the message with the

216 * sequence number matching the input. If zero is

217 * specified as the seqno, the first message in the

218 * queue will be peeked.

219 *

220 * Only the following trailer types are currently supported:

221 * MACH_RCV_TRAILER_TYPE(MACH_MSG_TRAILER_FORMAT_0)

222 *

223 * or'ed with one of these element types:

224 * MACH_RCV_TRAILER_ELEMENTS(MACH_RCV_TRAILER_NULL)

225 * MACH_RCV_TRAILER_ELEMENTS(MACH_RCV_TRAILER_SEQNO)

226 * MACH_RCV_TRAILER_ELEMENTS(MACH_RCV_TRAILER_SENDER)

227 * MACH_RCV_TRAILER_ELEMENTS(MACH_RCV_TRAILER_AUDIT)

228 */

229 routine mach_port_peek(

230 task : ipc_space_t;

231 name : mach_port_name_t;

232 trailer_type : mach_msg_trailer_type_t;

233 inout request_seqnop : mach_port_seqno_t;

234 out msg_sizep : mach_msg_size_t;

235 out msg_idp : mach_msg_id_t;

236 out trailer_infop : mach_msg_trailer_info_t, CountInOut);

237

238 /*

239 * Only valid for receive rights.

240 * Sets the make-send count for the port.

241 */

242 routine mach_port_set_mscount(

243 task : ipc_space_t;

244 name : mach_port_name_t;

245 mscount : mach_port_mscount_t);

246

247 /*

248 * Only valid for port sets. Returns a list of

249 * the members.

250 */

251 routine

252 #ifdef KERNEL_SERVER

253 mach_port_get_set_status_from_user(

254 port : mach_port_t;

255 #else

256 mach_port_get_set_status(

257 task : ipc_space_read_t;

258 #endif

259 name : mach_port_name_t;

260 out members : mach_port_name_array_t);

261

262 /*

263 * Puts the member port (the task must have receive rights)

264 * into the after port set. If the port is already a member

265 * of any set(s), it is atomically removed from those sets as

266 * part of this operation. (If after is MACH_PORT_NULL, the

267 * port is still removed from all current sets).

268 */

269

270 routine mach_port_move_member(

271 task : ipc_space_t;

272 member : mach_port_name_t;

273 after : mach_port_name_t);

274

275 /*

276 * Requests a notification from the kernel. The request

277 * must supply the send-once right which is used for

278 * the notification. If a send-once right was previously

279 * registered, it is returned. The msgid must be one of:

280 * MACH_NOTIFY_PORT_DESTROYED (receive rights)

281 * MACH_NOTIFY_DEAD_NAME (send/receive/send-once rights)

282 * MACH_NOTIFY_SEND_POSSIBLE (send/receive/send-once rights)

283 * MACH_NOTIFY_NO_SENDERS (receive rights)

284 *

285 * The sync value specifies whether a notification should

286 * get sent immediately, if appropriate. The exact meaning

287 * depends on the notification:

288 * MACH_NOTIFY_PORT_DESTROYED: must be zero.

289 * MACH_NOTIFY_DEAD_NAME: if non-zero, then name can be dead,

290 * and the notification gets sent immediately.

291 * If zero, then name can't be dead.

292 * MACH_NOTIFY_SEND_POSSIBLE: if non-zero, will generate a send-

293 * possible notification as soon as it is possible to send

294 * to the port. If zero, will generate a send-possible

295 * notification only after a subsequent failed send

296 * (with MACH_SEND_NOTIFY option to mach_msg call). Can

297 * generate a dead-name notification if name is already dead

298 * or becomes dead before a send-possible notification fires.

299 * MACH_NOTIFY_NO_SENDERS: the notification gets sent

300 * immediately if the current mscount is greater

301 * than or equal to the sync value and there are no

302 * extant send rights.

303 *

304 * If the name is deleted before a successfully registered notification

305 * is delivered, it is replaced with a port-deleted notification.

306 */

307

308 routine mach_port_request_notification(

309 task : ipc_space_t;

310 name : mach_port_name_t;

311 msgid : mach_msg_id_t;

312 sync : mach_port_mscount_t;

313 notify : mach_port_send_once_t;

314 out previous : mach_port_move_send_once_t);

315

316 /*

317 * Inserts the specified rights into the target task,

318 * using the specified name. If inserting send/receive

319 * rights and the task already has send/receive rights

320 * for the port, then the names must agree. In any case,

321 * the task gains a user ref for the port.

322 */

323

324 routine mach_port_insert_right(

325 task : ipc_space_t;

326 name : mach_port_name_t;

327 poly : mach_port_poly_t);

328

329 /*

330 * Returns the specified right for the named port

331 * in the target task, extracting that right from

332 * the target task. The target task loses a user

333 * ref and the name may be available for recycling.

334 * msgt_name must be one of

335 * MACH_MSG_TYPE_MOVE_RECEIVE

336 * MACH_MSG_TYPE_COPY_SEND

337 * MACH_MSG_TYPE_MAKE_SEND

338 * MACH_MSG_TYPE_MOVE_SEND

339 * MACH_MSG_TYPE_MAKE_SEND_ONCE

340 * MACH_MSG_TYPE_MOVE_SEND_ONCE

341 */

342

343 routine mach_port_extract_right(

344 task : ipc_space_t;

345 name : mach_port_name_t;

346 msgt_name : mach_msg_type_name_t;

347 out poly : mach_port_poly_t);

348

349 /*

350 * Only valid for receive rights.

351 * Sets the sequence number for the port.

352 */

353

354 routine mach_port_set_seqno(

355 task : ipc_space_t;

356 name : mach_port_name_t;

357 seqno : mach_port_seqno_t);

358

359 /*

360 * Returns information about a port.

361 */

362 routine

363 #ifdef KERNEL_SERVER

364 mach_port_get_attributes_from_user(

365 port : mach_port_t;

366 #else

367 mach_port_get_attributes(

368 task : ipc_space_read_t;

369 #endif

370 name : mach_port_name_t;

371 flavor : mach_port_flavor_t;

372 out port_info_out : mach_port_info_t, CountInOut);

373

374 /*

375 * Set attributes of a port

376 */

377

378 routine mach_port_set_attributes(

379 task : ipc_space_t;

380 name : mach_port_name_t;

381 flavor : mach_port_flavor_t;

382 port_info : mach_port_info_t);

383

384

385 /*

386 * Allocates the specified kind of object, qos version.

387 * The right must be

388 * MACH_PORT_RIGHT_RECEIVE

389 * Like port_allocate_name, but the kernel picks a name.

390 * It can use any name not associated with a right.

391 */

392

393 routine mach_port_allocate_qos(

394 task : ipc_space_t;

395 right : mach_port_right_t;

396 inout qos : mach_port_qos_t;

397 out name : mach_port_name_t);

398

399

400 /*

401 * Generic interface to allocation various kinds of ports.

402 * Should never be called directly by users (at least not

403 * unless they are exceedingly masochistic).

404 */

405

406 routine mach_port_allocate_full(

407 task : ipc_space_t;

408 right : mach_port_right_t;

409 proto : mach_port_t;

410 inout qos : mach_port_qos_t;

411 inout name : mach_port_name_t);

412

413

414 /*

415 * Pre-expand task port name space.

416 */

417 routine task_set_port_space(

418 task : ipc_space_t;

419 table_entries : int);

420

421

422 /*

423 * Returns the exact number of extant send rights

424 * for the given receive right.

425 * This call is only valid on MACH_IPC_DEBUG kernels.

426 * Otherwise, KERN_FAILURE is returned.

427 */

428 routine mach_port_get_srights(

429 task : ipc_space_t;

430 name : mach_port_name_t;

431 out srights : mach_port_rights_t);

432

433

434 /*

435 * Returns information about an IPC space.

436 * This call is only valid on MACH_IPC_DEBUG kernels.

437 * Otherwise, KERN_FAILURE is returned.

438 */

439 routine

440 #ifdef KERNEL_SERVER

441 mach_port_space_info_from_user(

442 port : mach_port_t;

443 #else

444 mach_port_space_info(

445 space : ipc_space_read_t;

446 #endif

447 out space_info : ipc_info_space_t;

448 out table_info : ipc_info_name_array_t;

449 out tree_info : ipc_info_tree_name_array_t);

450

451 /*

452 * Returns information about the dead-name requests

453 * registered with the named receive right.

454 * This call is only valid on MACH_IPC_DEBUG kernels.

455 * Otherwise, KERN_FAILURE is returned.

456 */

457 routine mach_port_dnrequest_info(

458 task : ipc_space_t;

459 name : mach_port_name_t;

460 out dnr_total : unsigned; /* total size of table */

461 out dnr_used : unsigned); /* amount used */

462

463 /*

464 * Return the type and address of the kernel object

465 * that the given send/receive right represents.

466 * This call is only valid on MACH_IPC_DEBUG kernels.

467 * Otherwise, KERN_FAILURE is returned.

468 *

469 * This interface is DEPRECATED in favor of the new

470 * mach_port_kernel_object64() call (see below).

471 */

472 routine

473 #ifdef KERNEL_SERVER

474 mach_port_kernel_object_from_user(

475 port : mach_port_t;

476 #else

477 mach_port_kernel_object(

478 task : ipc_space_read_t;

479 #endif

480 name : mach_port_name_t;

481 out object_type : unsigned;

482 out object_addr : unsigned);

483

484

485 /*

486 * Inserts the specified rights into the portset identified

487 * by the <task, pset> pair. The results of passing in the

488 * Poly argument via the supplied disposition must yield a

489 * receive right.

490 *

491 * If the <task,pset> pair does not represent a valid portset

492 * KERN_INVALID_RIGHT is returned.

493 *

494 * If the passed in name argument does not represent a receive

495 * right, KERN_INVALID_CAPABILITY will be returned.

496 *

497 * If the port represented by the receive right is already in

498 * the portset, KERN_ALREADY_IN_SET is returned.

499 */

500 routine mach_port_insert_member(

501 task : ipc_space_t;

502 name : mach_port_name_t;

503 pset : mach_port_name_t);

504

505 /*

506 * Extracts the specified right from the named portset

507 * in the target task.

508 * the target task. The target task loses a user

509 * ref and the name may be available for recycling.

510 * msgt_name must be one of

511 * MACH_MSG_TYPE_MOVE_RECEIVE

512 * MACH_MSG_TYPE_COPY_SEND

513 * MACH_MSG_TYPE_MAKE_SEND

514 * MACH_MSG_TYPE_MOVE_SEND

515 * MACH_MSG_TYPE_MAKE_SEND_ONCE

516 * MACH_MSG_TYPE_MOVE_SEND_ONCE

517 */

518

519 routine mach_port_extract_member(

520 task : ipc_space_t;

521 name : mach_port_name_t;

522 pset : mach_port_name_t);

523

524 /*

525 * Only valid for receive rights.

526 * Gets the context pointer for the port.

527 */

528 routine

529 #ifdef KERNEL_SERVER

530 mach_port_get_context_from_user(

531 port : mach_port_t;

532 #else

533 mach_port_get_context(

534 task : ipc_space_read_t;

535 #endif

536 name : mach_port_name_t;

537 #ifdef LIBSYSCALL_INTERFACE

538 out context : mach_port_context_t

539 #else

540 out context : mach_vm_address_t

541 #endif

542 );

543

544 /*

545 * Only valid for receive rights.

546 * Sets the context pointer for the port.

547 */

548

549 routine mach_port_set_context(

550 task : ipc_space_t;

551 name : mach_port_name_t;

552 #ifdef LIBSYSCALL_INTERFACE

553 context : mach_port_context_t

554 #else

555 context : mach_vm_address_t

556 #endif

557 );

558

559 /*

560 * Return the type and address of the kernel object

561 * that the given send/receive right represents.

562 * This call is only valid on MACH_IPC_DEBUG kernels.

563 * Otherwise, KERN_FAILURE is returned.

564 */

565 routine

566 #ifdef KERNEL_SERVER

567 mach_port_kobject_from_user(

568 port : mach_port_t;

569 #else

570 mach_port_kobject(

571 task : ipc_space_read_t;

572 #endif

573 name : mach_port_name_t;

574 out object_type : natural_t;

575 out object_addr : mach_vm_address_t);

576

577

578 /*

579 * Constructs a right based on the options passed

580 * in. Also allows guarding the port as one of the

581 * options if the requested right is a receive

582 * right.

583 */

584 routine mach_port_construct(

585 task : ipc_space_t;

586 options : mach_port_options_ptr_t;

587 #ifdef LIBSYSCALL_INTERFACE

588 context : mach_port_context_t;

589 #else

590 context : uint64_t;

591 #endif

592 out name : mach_port_name_t);

593

594 /*

595 * Destroys a mach port using the guard provided

596 * for guarded ports. Also reduces the user ref

597 * count for send rights as specified by srdelta.

598 */

599 routine mach_port_destruct(

600 task : ipc_space_t;

601 name : mach_port_name_t;

602 srdelta : mach_port_delta_t;

603 #ifdef LIBSYSCALL_INTERFACE

604 guard : mach_port_context_t

605 #else

606 guard : uint64_t

607 #endif

608 );

609

610 /*

611 * Guard an already existing port. Allows guarding

612 * receive rights only. Uses the context field in the

613 * port structure to store the guard.

614 */

615 routine mach_port_guard(

616 task : ipc_space_t;

617 name : mach_port_name_t;

618 #ifdef LIBSYSCALL_INTERFACE

619 guard : mach_port_context_t;

620 #else

621 guard : uint64_t;

622 #endif

623 strict : boolean_t);

624

625 /*

626 * Unguard a port guarded previously. For unguarded ports

627 * or incorrect guards passed in it raises an exception

628 * indicating guarding misbehavior.

629 */

630 routine mach_port_unguard(

631 task : ipc_space_t;

632 name : mach_port_name_t;

633 #ifdef LIBSYSCALL_INTERFACE

634 guard : mach_port_context_t

635 #else

636 guard : uint64_t

637 #endif

638 );

639

640 /*

641 * Returns basic information about an IPC space.

642 * This call is only valid on MACH_IPC_DEBUG kernels.

643 * Otherwise, KERN_FAILURE is returned.

644 */

645 routine mach_port_space_basic_info(

646 task : ipc_space_inspect_t;

647 out basic_info : ipc_info_space_basic_t);

648

649 #if KERNEL || !LIBSYSCALL_INTERFACE

650 /*

651 * Returns sync ipc turnstile link status

652 * for special reply ports.

653 */

654 routine mach_port_special_reply_port_reset_link(

655 task : ipc_space_t;

656 name : mach_port_name_t;

657 out srp_lost_link : boolean_t);

658 #else

659 skip;

660 #endif

661

662 /*

663 * Guard an already existing port. Allows guarding

664 * receive rights only. Uses the context field in the

665 * port structure to store the guard.

666 */

667 routine mach_port_guard_with_flags(

668 task : ipc_space_t;

669 name : mach_port_name_t;

670 #ifdef LIBSYSCALL_INTERFACE

671 guard : mach_port_context_t;

672 #else

673 guard : uint64_t;

674 #endif

675 flags : uint64_t);

676

677 /*

678 * Swap guard value of an existing guarded port. Works

679 * only if it is not a strict guard.

680 */

681 routine mach_port_swap_guard(

682 task : ipc_space_t;

683 name : mach_port_name_t;

684 #ifdef LIBSYSCALL_INTERFACE

685 old_guard : mach_port_context_t;

686 #else

687 old_guard : uint64_t;

688 #endif

689

690 #ifdef LIBSYSCALL_INTERFACE

691 new_guard : mach_port_context_t);

692 #else

693 new_guard : uint64_t);

694 #endif

695

696 /*

697 * Return the type and address of the kernel object

698 * that the given send/receive right represents.

699 * This call is only valid on MACH_IPC_DEBUG kernels.

700 * Otherwise, KERN_FAILURE is returned.

701 */

702 routine

703 #ifdef KERNEL_SERVER

704 mach_port_kobject_description_from_user(

705 port : mach_port_t;

706 #else

707 mach_port_kobject_description(

708 task : ipc_space_read_t;

709 #endif

710 name : mach_port_name_t;

711 out object_type : natural_t;

712 out object_addr : mach_vm_address_t;

713 out description : kobject_description_t);

714

715 /* vim: set ft=c : */