document general shim pattern

Author: RalfJung

src/shims/foreign_items.rs

@@ -366,6 +366,18 @@ pub trait EvalContextExt<'mir, 'tcx: 'mir>: crate::MiriEvalContextExt<'mir, 'tcx
     ) -> InterpResult<'tcx, EmulateByNameResult<'mir, 'tcx>> {
         let this = self.eval_context_mut();
 
+        // When adding a new shim, you should follow the following pattern:
+        // ```
+        // "shim_name" => {
+        //     let [arg1, arg2, arg3] = this.check_shim(abi, Abi::C { unwind: false }, link_name, args)?;
+        //     let result = this.shim_name(arg1, arg2, arg3)?;
+        //     this.write_scalar(result, dest)?;
+        // }
+        // ```
+        // and then define `shim_name` as a helper function in an extension trait in a suitable file
+        // (see e.g. `unix/fs.rs`). You might find existing shims not following this pattern, most
+        // likely because they predate it or because for some reason they cannot be made to fit.
+
         // Here we dispatch all the shims for foreign functions. If you have a platform specific
         // shim, add it to the corresponding submodule.
         match link_name.as_str() {

src/shims/unix/foreign_items.rs

@@ -24,6 +24,8 @@ pub trait EvalContextExt<'mir, 'tcx: 'mir>: crate::MiriEvalContextExt<'mir, 'tcx
     ) -> InterpResult<'tcx, EmulateByNameResult<'mir, 'tcx>> {
         let this = self.eval_context_mut();
 
+        // See `fn emulate_foreign_item_by_name` in `shims/foreign_items.rs` for the general pattern.
+
         match link_name.as_str() {
             // Environment related shims
             "getenv" => {

src/shims/unix/linux/foreign_items.rs

@@ -19,6 +19,8 @@ pub trait EvalContextExt<'mir, 'tcx: 'mir>: crate::MiriEvalContextExt<'mir, 'tcx
     ) -> InterpResult<'tcx, EmulateByNameResult<'mir, 'tcx>> {
         let this = self.eval_context_mut();
 
+        // See `fn emulate_foreign_item_by_name` in `shims/foreign_items.rs` for the general pattern.
+
         match link_name.as_str() {
             // errno
             "__errno_location" => {

src/shims/unix/macos/foreign_items.rs

@@ -17,6 +17,8 @@ pub trait EvalContextExt<'mir, 'tcx: 'mir>: crate::MiriEvalContextExt<'mir, 'tcx
     ) -> InterpResult<'tcx, EmulateByNameResult<'mir, 'tcx>> {
         let this = self.eval_context_mut();
 
+        // See `fn emulate_foreign_item_by_name` in `shims/foreign_items.rs` for the general pattern.
+
         match link_name.as_str() {
             // errno
             "__error" => {

src/shims/windows/foreign_items.rs

@@ -20,6 +20,8 @@ pub trait EvalContextExt<'mir, 'tcx: 'mir>: crate::MiriEvalContextExt<'mir, 'tcx
     ) -> InterpResult<'tcx, EmulateByNameResult<'mir, 'tcx>> {
         let this = self.eval_context_mut();
 
+        // See `fn emulate_foreign_item_by_name` in `shims/foreign_items.rs` for the general pattern.
+
         // Windows API stubs.
         // HANDLE = isize
         // NTSTATUS = LONH = i32