From a00240bfe14c2e3b87be64db1e8e8e9cda8415a0 Mon Sep 17 00:00:00 2001 From: Richard Lander Date: Mon, 9 Feb 2015 08:23:41 -0800 Subject: [PATCH] Update mscorlib doc and add entry to readme --- Documentation/mscorlib.md | 125 +++++++++++++++++++++++----------------------- README.md | 10 +++- 2 files changed, 72 insertions(+), 63 deletions(-) diff --git a/Documentation/mscorlib.md b/Documentation/mscorlib.md index 8fe3a91..29edef3 100644 --- a/Documentation/mscorlib.md +++ b/Documentation/mscorlib.md @@ -1,4 +1,5 @@ -#Mscorlib and Calling Into the Runtime +Mscorlib and Calling Into the Runtime +=== Author: Brian Grunkemeyer (@briangru) - 2006 # Introduction @@ -80,26 +81,26 @@ Do not replicate the comments into your actual QCall implementation. This is for class Foo { - // All QCalls should have the following DllImport and - // SuppressUnmanagedCodeSecurity attributes - [DllImport(JitHelpers.QCall, CharSet = CharSet.Unicode)] - [SuppressUnmanagedCodeSecurity] - // QCalls should always be static extern. - private static extern bool Bar(int flags, string inString, StringHandleOnStack retString); - - // Many QCalls have a thin managed wrapper around them to expose them to - // the world in more meaningful way. - public string Bar(int flags) - { - string retString = null; - - // The strings are returned from QCalls by taking address - // of a local variable using JitHelpers.GetStringHandle method - if (!Bar(flags, this.Id, JitHelpers.GetStringHandle(ref retString))) - FatalError(); - + // All QCalls should have the following DllImport and + // SuppressUnmanagedCodeSecurity attributes + [DllImport(JitHelpers.QCall, CharSet = CharSet.Unicode)] + [SuppressUnmanagedCodeSecurity] + // QCalls should always be static extern. + private static extern bool Bar(int flags, string inString, StringHandleOnStack retString); + + // Many QCalls have a thin managed wrapper around them to expose them to + // the world in more meaningful way. + public string Bar(int flags) + { + string retString = null; + + // The strings are returned from QCalls by taking address + // of a local variable using JitHelpers.GetStringHandle method + if (!Bar(flags, this.Id, JitHelpers.GetStringHandle(ref retString))) + FatalError(); + return retString; - } + } } ### QCall Example - Unmanaged Part @@ -110,7 +111,7 @@ The QCall entrypoint has to be registered in tables in [vm\ecalllist.h][ecalllis [ecalllist]: https://github.com/dotnet/coreclr/blob/master/src/vm/ecalllist.h -class FooNative + class FooNative { public: // All QCalls should be static and should be tagged with QCALLTYPE @@ -120,47 +121,47 @@ class FooNative BOOL QCALLTYPE FooNative::Bar(int flags, LPCWSTR wszString, QCall::StringHandleOnStack retString) { - // All QCalls should have QCALL_CONTRACT. - // It is alias for THROWS; GC_TRIGGERS; MODE_PREEMPTIVE; SO_TOLERANT. - QCALL_CONTRACT; - - // Optionally, use QCALL_CHECK instead and the expanded form of the contract - // if you want to specify preconditions: - // CONTRACTL { - // QCALL_CHECK; - // PRECONDITION(wszString != NULL); - // } CONTRACTL_END; - - // The only line between QCALL_CONTRACT and BEGIN_QCALL - // should be the return value declaration if there is one. - BOOL retVal = FALSE; - - // The body has to be enclosed in BEGIN_QCALL/END_QCALL macro. It is necessary - // to make the exception handling work. - BEGIN_QCALL; - - // Validate arguments if necessary and throw exceptions. - // There is no convention currently on whether the argument validation should be - // done in managed or unmanaged code. - if (flags != 0) - COMPlusThrow(kArgumentException, L"InvalidFlags"); - - // No need to worry about GC moving strings passed into QCall. - // Marshalling pins them for us. - printf("%S", wszString); - - // This is most the efficient way to return strings back - // to managed code. No need to use StringBuilder. - retString.Set(L"Hello"); - - // You can not return from inside of BEGIN_QCALL/END_QCALL. - // The return value has to be passed out in helper variable. - retVal = TRUE; - - END_QCALL; - - return retVal; - } + // All QCalls should have QCALL_CONTRACT. + // It is alias for THROWS; GC_TRIGGERS; MODE_PREEMPTIVE; SO_TOLERANT. + QCALL_CONTRACT; + + // Optionally, use QCALL_CHECK instead and the expanded form of the contract + // if you want to specify preconditions: + // CONTRACTL { + // QCALL_CHECK; + // PRECONDITION(wszString != NULL); + // } CONTRACTL_END; + + // The only line between QCALL_CONTRACT and BEGIN_QCALL + // should be the return value declaration if there is one. + BOOL retVal = FALSE; + + // The body has to be enclosed in BEGIN_QCALL/END_QCALL macro. It is necessary + // to make the exception handling work. + BEGIN_QCALL; + + // Validate arguments if necessary and throw exceptions. + // There is no convention currently on whether the argument validation should be + // done in managed or unmanaged code. + if (flags != 0) + COMPlusThrow(kArgumentException, L"InvalidFlags"); + + // No need to worry about GC moving strings passed into QCall. + // Marshalling pins them for us. + printf("%S", wszString); + + // This is most the efficient way to return strings back + // to managed code. No need to use StringBuilder. + retString.Set(L"Hello"); + + // You can not return from inside of BEGIN_QCALL/END_QCALL. + // The return value has to be passed out in helper variable. + retVal = TRUE; + + END_QCALL; + + return retVal; + } ## FCall Functional Behavior diff --git a/README.md b/README.md index 4ce372d..c4f90c2 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,5 @@ -# .NET Core Runtime (CoreCLR) +.NET Core Runtime (CoreCLR) +=== | |Linux|Windows| |:-:|:-:|:-:| @@ -11,6 +12,13 @@ The coreclr repo contains the complete runtime implementation (called "CoreCLR") The [.NET Core Libraries][corefx] repo contains the base class libraries, which provides data types and base functionality (ex: String, Collections, HttpClient) on top of CoreCLR. The two repos together make up .NET Core. The [.NET Core is Open Source][.NET Core oss] and [Introducing .NET Core][Introducing .NET Core] blog posts describes our .NET Core OSS strategy and road map in more detail. +## Learn about CoreCLR +Historically, new devs to the CLR team would be encouraged to read the "Book of the Runtime" (BotR) before making substative changes to the product. We have released the meaningful BotR chapters, for the same goal with new contributors. + +- [Introduction to the Common Language Runtime](https://github.com/dotnet/coreclr/blob/master/Documentation/intro-to-clr.md) +- [Mscorlib and Calling Into the Runtime](https://github.com/dotnet/coreclr/blob/master/Documentation/mscorlib.md) +- More coming + ## How to Engage, Contribute and Provide Feedback Some of the best ways to contribute are to try things out, file bugs, and join in design conversations. -- 2.7.4